Errors and response codes

Every API error response follows the same format, regardless of endpoint:

{ "message": "Error description" }

When the error is a validation error, an errors object with per-field detail is also included:

{
  "message": "The country code field is required.",
  "errors": {
    "country_code": ["The country code field is required."]
  }
}

API messages are always in English

Regardless of the language configured on your account or browser, the messages the API returns are always in English — it's the standard language for system-to-system integrations. Your application should map these messages (or the HTTP status codes) to whatever you show your own end users.

Status codes

Code	Meaning	When it happens
200 OK	Success	Successful read.
401 Unauthorized	Not authenticated	The token is missing, invalid, or revoked.
403 Forbidden	Access not enabled	Your token isn't valid for this audience, or your access isn't enabled — see Authentication for each case's detail.
404 Not Found	Not found	The requested resource doesn't exist, or it belongs to another customer — deliberately not distinguished, to avoid revealing that someone else's id exists.
422 Unprocessable Content	Validation failed	The submitted data doesn't meet validation rules — see errors.
429 Too Many Requests	Limit exceeded	See Rate Limits.
500 Server Error	Internal error	Something failed on our end. The detail is never exposed in the response — if you hit one repeatedly, contact us with the response's X-Request-Id (see below).

Request correlation

Every response includes an X-Request-Id header:

X-Request-Id: 765ba059-d6dc-44d8-a744-047a689e9e33

If you need to report an issue, include this value — it lets us locate that exact request in our logs without you having to share sensitive payload data.

Other HTTP errors

405 Method Not Allowed means the URL does not support the method you sent. Read the Allow header and use a documented method. It is not an internal server failure. Other HTTP errors preserve their status and relevant headers (for example, Retry-After on 503). Unexpected application failures return 500 with a generic message and no internal trace.