Our API's error codes: what each one means, and which ones are worth retrying

The short answer: every error has the same shape, with a stable code in English, which is what your program should compare. Only 429, 500, 502 and 503 are worth retrying, with a wait. The others are not fixed by retrying: something has to change.

The shape of an error

{
"error": {
"code": "rate_limited",
"message": "Too many requests. Try again shortly.",
"correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
"details": { "retry_after": 42 }
}
}

Field	What it is
code	A stable code, in English. Use this field in your programs: it never changes with the language.
message	Text for people, in the Accept-Language language (pt or en; without the header, English). It can change: do not compare it.
correlation_id	The request identifier, the same as the X-Correlation-ID header.
details	Extra data about the error, such as the invalid field or the reason for a 409. It may be empty.

The codes, one by one

Status and code	What it means	What to do
400 invalid_request	The request is not valid: the body is not JSON, the connection is not HTTPS, or the mode in X-API-Mode does not match the key.	Fix the request.
401 unauthorized	The key is missing, invalid, revoked or expired, or its creator no longer has access to the account.	Check the key or create another.
402 insufficient_credit	The account does not have enough credit. Nothing was charged.	Top up your credit and try again.
403 forbidden	The account cannot use the API right now.	Contact support.
403 insufficient_scope	The key lacks the required permission.	Create a key with that permission.
403 ip_not_allowed	The source IP is not on the key's list.	Use an IP from the list or create another key.
403 spending_limit_exceeded	The operation goes over the key's spending limit. Nothing was charged.	Create a key with a higher limit.
404 not_found	The resource does not exist or is not yours.	Check the address and the identifier.
405 method_not_allowed	The method is not accepted on this path.	See the Allow header.
409 conflict	It cannot be done in the current state. The reason is in details.reason.	Read the reason and fix it.
409 account_email_domain	The request touches the mail of the account e-mail's domain, or that of one of its users.	Make the change in Meu Interweb.
409 idempotency_conflict	The Idempotency-Key was used on another request, or the first one is still running.	See retries.
422 validation_failed	Some data is not valid.	Fix it, with help from details.
429 rate_limited	You went over the request limit.	Wait for the Retry-After time.
500 internal_error	A failure on our side.	Try later and give the correlation_id to support.
502 upstream_error	The service behind the API did not answer as expected.	Try later and give the correlation_id to support.
503 disabled	The API is switched off right now.	Try later.

There is also an SMS-specific code, 403 sms_reseller_required, when the account has no active SMS reseller program. Each area also has its own reasons inside 409 and 422, such as cname_conflict in DNS or action_in_progress for servers: they are in each area's article.

Retry or not

1	Retry, with a wait: 429, 500, 502 and 503. On a 429, wait at least the Retry-After time; if it repeats, wait longer each time.

2	Do not retry without changing something: all the others. A 422 keeps coming back as long as the data is wrong.

3	On a POST, always send Idempotency-Key from the first attempt and retry with the same value. That way, retrying after a 500 never does the same thing twice: see the Idempotency-Key.

A 502 on hosting may mean the change was made. If the request had already gone on to the server, retrying with the same Idempotency-Key returns the same 502 without running it again. Check the result with a read first and, to try again, use a new idempotency key.

Reporting a problem to support

Give the correlation_id (or the X-Correlation-ID header), the time of the request and the operation. Never send the key: support does not need it to find the request.

For your code: decide by the HTTP status (retry or not) and by the code (what to show or do), and always log the correlation_id. Never compare the message: it changes with the language and its wording may change.

Got an error you cannot make sense of? Open a support ticket with the correlation_id, the time and the operation, but never the key.

Open a support ticket

Categories

Categories