Vocatech

In depth

Rate limits

Written beside the API’s code, and read from it every hour.

Plain text

Limits are counted per key, in fixed windows in UTC, each minute, each hour, and each day from 00:00 UTC. Each kind of request has its own counter, so polling reports never uses up your room to send a text.

CounterCountsPer minutePer hourPer day
defaultEvery request not listed below6003,600100,000
reportsGET /v1/calls, GET /v1/messages, /v1/reports/*3003,000100,000
messagesPOST /v1/messagesNoneNone100,000 requests, as a backstop
faxesPOST /v1/faxes, per account3None50 faxes sent (Eastern day)
dialPOST /v1/agents/{id}/calls10None500
ticketsPOST /v1/support/tickets, GET /v1/support/tickets/{key}10None200
knowledgeGET or POST /v1/knowledge/answer30None2,000
  • Every request counts, including requests that were refused.
  • A request without a live key (no key, a wrong key, a key turned off) counts against its source address instead, 60 a minute and 600 an hour.
  • Sending a text has no request limit of its own beyond that backstop. Every key's texts are paced by its queue (see The message queue), 60 message parts a minute, and 5,000 texts a day for a key locked to fixed addresses or 500 a day for a key that works from any address. A text past the minute is accepted and queued (202). A text past the day is answered 429.
  • Texts sent through the API are paid, $0.02 for each outgoing part, and are outside the account's included texting limit, which counts only the texts the account's people send.
  • Faxes are counted per account, not per key. The 50 a day counts faxes actually sent. A dry run or a refused request does not use one.
  • Faxes also stop at the account's monthly allowance of outbound pages, 1,000 for each fax line on the account unless Vocatech set another figure, pooled across the lines.

Over a limit, the API answers 429 with a Retry-After header, the seconds until the window resets. The body names the window, the limit and the counter.

Response429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "period": "minute",
  "limit": 300,
  "counter": "reports",
  "retry_after": 37
}

When a key's day of texts is used up, the body says so in words. A key with no address list is also told how to reach the larger day.

Response429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "message": "This key is limited to 5000 messages per day. 4990 have been sent in the last 24 hours and 10 are waiting in the queue, so this send does not fit today.",
  "period": "day",
  "limit": 5000,
  "used": 4990,
  "queued": 10,
  "retry_after": 36120
}

Back off and retry

Wait for Retry-After when it is there. Without it, back off exponentially with a little jitter. Retry 429 and 503. Never retry a text send that answered 504 without checking GET /v1/messages first, and stop rather than sleep for hours on a day limit.

# curl retries 408, 429, 500, 502, 503 and 504 by itself and honors
# Retry-After (curl 7.66 or newer). Use it on reads, never on text sends.
curl --retry 5 --retry-max-time 120 \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  https://api.vocatech.com/v1/calls

To stay well under the limits, use webhooks instead of polling, and ask for 500 rows a page.