Errors
The shape of an error response, and what each status code means.
Errors use ordinary HTTP status codes and always have the same body:
{
"error": "insufficient_funds",
"message": "Wallet balance is too low for this order",
"requestId": "req-4f"
}erroris a stable code you can branch on.messageis written for a person. Do not parse it.requestIdidentifies the request. Quote it when asking for help.
Status codes
| Status | Meaning |
|---|---|
400 | The request is malformed: bad JSON, a field of the wrong type, a bad Idempotency-Key. |
401 unauthorized | The API key is missing, wrong or revoked. |
402 insufficient_funds | The wallet cannot cover the order. Nothing was charged. |
403 | The account is suspended, or missing a feature this needs, for example reseller_suspended or numbers_disabled. |
404 not_found | No such resource on this side of the account. |
409 | The request conflicts with the current state, for example domain_taken or not_cancellable. |
422 | The request is well formed but cannot be carried out, for example no_offer or not_available. |
429 rate_limited | Too many requests. Slow down and retry. |
5xx | Something went wrong on our side, for example renewal_failed. Retry with the same Idempotency-Key. |
Retrying
429 and 5xx are safe to retry, with a short growing delay between attempts. For anything
that spends money, send an Idempotency-Key so a retry cannot buy twice.
Do not retry other 4xx responses unchanged; the answer will be the same.