Skip to main content

API Error Reference

Every API response carries a JSON body with two fields that describe the result:

{
  "status_code": 404,
  "status_message": "A description of the result."
}
  • status_code mirrors the HTTP status code of the response.
  • status_message is a human-readable description of the result.

Because status_code mirrors the HTTP status, you can branch on either the HTTP status line or the body field, and they will always agree.

Status Codes​

CodeMeaning
200Success.
400Bad request. The input was malformed or invalid (for example, an invalid host or contact SID).
401Authentication failed. Check your account SID and auth token.
403Forbidden. Either your IP address is not permitted for this API application, or the feature is not available on your current plan.
404Not found. The requested resource does not exist on your account.
409Conflict. The resource is in a state that does not allow the action (for example, pausing a contact that has not been confirmed).
422Validation failed. The request was understood but the data did not pass validation. The status_message describes what to fix.
429Rate limited or temporarily unavailable. See below.
500An unexpected server error occurred.

Retrying: 429​

A 429 is returned in two situations, both of which include a Retry-After header (in seconds) along with the RateLimit-* headers:

  1. Rate limiting: you exceeded the per-second or hourly limit. See What Are the API Rate Limits?.
  2. Temporary service condition: the API could not serve the request because of a transient infrastructure condition (for example, the database was briefly unavailable).

In both cases the correct behavior is the same: wait for the number of seconds indicated by Retry-After and retry the request. Do not treat a 429 as a permanent failure.

Handling Errors​

  • Treat 4xx codes as client errors: fix the request (400, 422), check authentication (401), check permissions or your plan (403), confirm the resource exists (404), or resolve the resource state (409).
  • Treat 429 as "retry after a short wait" using the Retry-After header.
  • Treat 500 as an unexpected server error; retrying after a short delay is reasonable.