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. |
Rate limits are per account or key, counted once across the whole service rather than per server: calling from several processes, or hitting a different server on a retry, spends the same budget.
Every API key also has a concurrency cap: at most 20 requests from one key may be in flight at
once, counted the same way across every server. A key that opens more than that — for example a
burst of parallel bulk checks — gets 429 rate_limited on the extra ones until an earlier
request finishes; this is separate from the per-minute rate limit above and does not share its
budget. Dashboard sessions are never capped this way.
Every 429 carries a Retry-After header, in whole seconds. For the per-minute rate limit it
is how long until the window resets; for the concurrency cap it is 1, since a slot can free up
the moment another in-flight request of the same key finishes, which is often sooner than a
second.
Retrying
429 and 5xx are safe to retry, with a short growing delay between attempts — wait at least
Retry-After before trying again. 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.