Vocatech

In depth

Errors

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

Plain text

Every error has a status code and a JSON body. Read the status first: it tells you what to do. The body comes in one of four shapes. The vt() helpers in the Quickstart read all four.

From an endpoint

Most errors. The message says what to fix.

Endpoint error400 Bad Request
{
  "error": {
    "code": 400,
    "type": "BAD_REQUEST",
    "message": "Ask for at most 366 days at a time (this request covers 400). For more history, walk it a year at a time."
  }
}

From the router

An unknown path, a method the path does not take, some not-found answers, and faults we did not expect.

Router error404 Not Found
{
  "statusCode": 404,
  "error": {
    "type": "RESOURCE_NOT_FOUND",
    "description": "Webhook not found."
  }
}

From the key check

401, 403 for a scope or an IP allow-list, and 503 when a key cannot be checked. Examples are in Authentication and keys.

Key check error503 Service Unavailable
{
  "error": "Service Unavailable",
  "message": "The API could not check this key just now. Retry in a few seconds."
}

From a rate limit

429, with retry_after in the body and a Retry-After header. See Rate limits.

Status codes

StatusWhenWhat to do
400A value is wrong or missing: a date, a number, a file, a window over 366 days, an end date before the start.Fix the request. The message names the field.
401No key, a wrong key, or a key that was turned off or regenerated.Check the key. Retrying will not help.
403The key's scope or IP allow-list refuses the request, or the action is not allowed: from is not your number, the recipient opted out, faxing is off.Read the message. Do not retry as is.
404Not found, not yours, or an unknown path.Check the id and the path.
405The path does not take that method.Use the method in the reference.
409A queued message is already sending or done, or a support ticket is busy (with Retry-After: 60).Treat it as done, or wait and send again.
410A message attachment is no longer available.There is nothing to fetch.
413A fax document over 20 MB.Send a smaller file.
422Validation: a webhook URL that is not public https, a missing event or message, WhatsApp sending, an AI agent call that cannot be placed.Fix the request. The message says what.
429A rate limit, a day allowance, or the monthly fax page limit.Wait Retry-After seconds.
500Something failed on our side, or the fax service refused a fax.Retry later with backoff. If it repeats, tell us the time and the path.
502A service behind the API answered and refused, or did not answer: the messaging service did not send, the support desk could not take it, or the agent platform did not answer and the call may have been placed.Read the message. For an AI agent call, check for the placed-call tag before you retry, or retry with the same Idempotency-Key. Otherwise retry in a minute if it says so.
503The key could not be checked (Retry-After: 5), a text could not reach the messaging service and was not sent, a desk is not available, or storage had trouble on our side.Safe to retry after a pause.
504A text send was not confirmed. It may have gone out.Check GET /v1/messages before retrying.
Before thisRate limitsNext Pages and dates