Errors

Errors come in a few JSON shapes, depending on the call and on where the request was refused. Branch on the HTTP status and, for reseller calls, on the stable code; never on the human-readable message, which is translated into the account’s language.

Error envelopes

Each operation in the reference lists, per status, the codes it can return and which body shape it uses; the body names link here.

ResellerError

Every coded refusal of a reseller call (/reseller/…):

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

Some codes add context next to code and message: fields, required, available, currency, required_years, allowed_years, registrar_message, retry_after. The codes are listed below.

ClientError

Refusals of the Domain management calls (/client/domains/…): the account or permission is wrong, the domain is not yours, or the registry refused or could not be reached.

{
  "success": false,
  "message": "The registrar could not be reached."
}

The same shape answers the IP-whitelist check with status 403 on Domain management calls: "IP not allowed" (the call comes from outside the whitelist) or "IP whitelist misconfigured" (the whitelist cannot be read, so every call is refused until you fix it in the client area). Reseller calls answer the same refusals as a ResellerError with code ip_not_allowed or ip_whitelist_misconfigured.

ValidationError

Invalid input on a Domain management call answers 422 with one list of messages per field:

{
  "message": "The nameservers field must have at least 2 items.",
  "errors": {
    "nameservers": ["The nameservers field must have at least 2 items."]
  }
}

MessageError

Answers produced before the call reaches the API logic carry only a message:

{
  "message": "Unauthenticated."
}

Responses outside the envelopes

These answers never carry an error code, on any route:

Reseller error codes

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