Skip to content
DNA Rest API

Error format

View as MarkdownOpen in ClaudeOpen in ChatGPT

Every error carries the same envelope:

{
  "error": {
    "code": "Dna.DomainService:Domain:10007",
    "message": "The domain name you requested could not be found. Please check and try again.",
    "details": "apiname.com was not found"
  }
}
Field Use it for
code Your logic. Stable and contractual — it does not change.
message Showing the user. Localised, and we reword it over time.
details Your logs. Says which domain, which field, which limit.

Validation errors

Section titled “Validation errors”

When a request fails field validation, the envelope gains a validationErrors array telling you exactly which fields were wrong. The members entry is prefixed with the contact role when the problem is in a contact, so you can map it straight onto your form.

{
  "error": {
    "code": "Dna.DomainService:ValidationError",
    "message": "Validation failed. Please check the provided information.",
    "validationErrors": [
      {
        "message": "Registrant Country is required.",
        "members": ["Registrant.Country"]
      },
      {
        "message": "Admin PhoneCountryCode must contain only digits (e.g., 90). Please do not use the '+' sign.",
        "members": ["Admin.PhoneCountryCode"]
      }
    ]
  }
}

Insufficient balance

Section titled “Insufficient balance”

Balance errors add a data object so you can tell the user exactly how much to top up, without a second API call.

{
  "error": {
    "code": "Dna.DomainService:Deposit:10001",
    "message": "Insufficient balance",
    "details": "Your balance is insufficient to complete this transaction.",
    "data": {
      "tryBalance": 120.50,
      "usdBalance": 3.10,
      "requiredAmount": 11.40,
      "requiredAmountCurrency": "USD"
    }
  }
}

Reading error codes

Section titled “Reading error codes”

Codes are structured as Service:Area:Number. The area tells you where to look first:

  • …:Domain: — domain operations
  • …:Contact: — contact data
  • …:Contact:Verification: — e-mail / ownership verification
  • …:Dns: — name servers and glue
  • …:Dnssec: — DNSSEC
  • …:TldAttribute: — TLD-specific extra fields
  • …:Deposit: — balance
  • …:Reseller: — account state
  • ZoneClient: — DNS records
  • Ssl: — certificates

The full catalogue is in Error codes.