Errors

Every error, on every call, is one JSON envelope with the matching HTTP status. Branch on the stable code; never on message, which is English text for logs and people and may change. Errors are always JSON, whatever Accept header you send.

The error envelope

{
  "error": {
    "code": "insufficient_credit",
    "message": "Insufficient credit for this operation. Nothing was charged.",
    "required": 12.2,
    "available": 3.0,
    "currency": "EUR"
  }
}

• code — always present. Stable and machine-readable: the value to branch on.
• message — always present. English, human-readable; never parse it.
• fields — only on validation failures (422 invalid_request, and the reseller invalid_contact): each field with its messages.
• retry_after — seconds to wait, on 429 rate_limited, 503 service_unavailable and 409 idempotency_in_progress.
• Other named context on some codes: permission and ability on a refused token; required, available, currency, required_years, allowed_years, registrar_message on reseller refusals.

Each operation in the reference lists, per status, the codes it can return.

Codes every call can meet

Validation errors

A 422 invalid_request lists every problem in fields, keyed by field name; the reseller invalid_contact does the same for the registrant and the extra fields:

{
  "error": {
    "code": "invalid_request",
    "message": "The request is not valid.",
    "fields": {
      "nameservers": ["At least 2 nameservers are required."]
    }
  }
}

Reseller codes

Reseller calls (/reseller/…) use the same envelope and add their own codes:

Retrying

• 429 rate_limited, 503 service_unavailable: wait retry_after seconds, then retry.
• 409 idempotency_in_progress: the first request with that Idempotency-Key is still running; retry after retry_after with the same key.
• 500 server_error on register, transfer, renew or restore: do not retry with a new key — contact SupportHost (see A key stuck in progress).
• Any other code: fix the request or the account state first; retrying unchanged gets the same answer.

New codes may be added over time: treat an unknown code like the generic meaning of its HTTP status.