# Error codes

> Every error code by area, with what it means and what to do, and the codes you must never retry.

Every error code grouped by area, with what it means and what to do. Branch your code on `code`, show the user `message`, log `details`.

## How to handle errors properly

1. **Read `code`, not `message`.** Messages are localised and get reworded. Codes do not change.
2. **Group codes by what you will do about them.** Most fall into four buckets: *fix the input and retry*, *tell the customer to do something*, *wait and retry*, and *never retry*.
3. **Log `details` and your `X-Correlation-ID` together.** These two make a support ticket resolvable in minutes.
4. **Handle the never-retry codes explicitly.** They are the only ones where a retry actively causes harm.

:::danger[Never retry these five]
| Code | What already happened |
| --- | --- |
| `Dna.DomainService:Domain:10058 *` | The domain **was registered** at the registry but we could not record it. |
| `Dna.DomainService:Domain:10059` | The domain **was renewed** at the registry but we could not record it. |
| `Dna.DomainService:Domain:10060` | The transfer **was started** at the registry but we could not record it. |
| `Ssl:10053` | SSL configuration has already been sent to the CA. |
| `Ssl:10054` | SSL configuration was sent but the outcome could not be verified. |

In every case the operation **succeeded** and a recovery record exists. Retrying creates a duplicate registration or a double charge. Open a support ticket with the domain name and your correlation ID.

\* `10058` has a second, harmless meaning — "Domain name mixes multiple scripts", which means your input was rejected and nothing happened. Read the message to tell them apart.
:::

:::caution[Four codes carry two meanings — read the message as well]
| Code | The two meanings |
| --- | --- |
| `Dna.DomainService:Domain:10058` | "created at the registry but not recorded" (never retry) **or** "mixes multiple scripts" (input rejected). |
| `Dna.DomainService:Domain:10025` | On `/transfers/check`: the extension has no transfer-check facility. On `/transfers/query`: the domain is not in a transfer state. |
| `Ssl:10048` | "certificate not issued yet" **or** "provider order number invalid". If `isIssued` is false, it is the former. |
| `Ssl:10049` | "revoke failed" **or** "the CA could not be reached". |
:::

## Authentication and account

| Code | Meaning and what to do |
| --- | --- |
| (plain text, 401) | Missing or invalid `X-API-KEY` / `__reseller`, or a sub-reseller account. See [Authentication](https://www.domainnameapi.com/docs/getting-started/authentication/). |
| `Dna.DomainService:Reseller:10001` | **Your balance is suspended.** Every paid operation is blocked. Contact us — this is an account matter, not something you can fix in code. |
| `Dna.DomainService:Deposit:10001` | Insufficient balance. `data` gives current balances and the required amount. Top up and retry. |
| `Ssl:10045 / Ssl:10047` | The SSL equivalents of the two above. |
| `Dna.DomainService:General:10001` | An internal error. Retry once; if it persists, open a ticket with your correlation ID. |
| `Dna.DomainService:Epp:10001` | The registry refused for a reason we have no specific code for. **Read `details`** — it carries the registry's own message, which is usually clear. |

## Domain errors

### Not found and ownership

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Domain:10007` | Domain not found, **or found but not yours**. We report ownership mismatches as not-found deliberately. |
| `Dna.DomainService:Domain:1021 / 1020 / 1023` | The domain does not belong to you, or to your sub-resellers. |
| `Dna.DomainService:Domain:1024 / 10030` | The domain already belongs to you, or to the reseller you specified. Nothing to do. |
| `Dna.DomainService:Domain:10050` | The domain is in our system but we cannot match the record. Open a ticket. |

### Name and format

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Domain:10005` | Invalid domain name. Check for a missing dot, a leading or trailing hyphen in a label, or an empty label. |
| `Dna.DomainService:Domain:10044` | Invalid domain name on a write operation. Same checks as above. |
| `Dna.DomainService:Domain:10058` | The name mixes alphabets within one label — rejected as a look-alike attack. See the note above about this code's second meaning. |
| `Dna.DomainService:Domain:10004` | We do not sell this extension. Do not retry. |
| `Dna.DomainService:Domain:10046` | You sent a subdomain where a registrable domain was expected. |
| `Dna.DomainService:Domain:10012 / 10013 / 10014` | The name is shorter or longer than this extension permits. |

### Period and pricing

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Domain:10023` | **Common.** Registering: the `period` is not one this extension sells. Read `registrationPeriods` from the catalogue. |
| `Dna.DomainService:Domain:10002` | Renewing: the `period` is not one of the extension's `renewalPeriods`. |
| `Dna.DomainService:Domain:10022` | `period` above 10. |
| `Dna.DomainService:Domain:1016` | Renewal check only: `period` is 0, or — as `errorMessageKey` — the term is too long (the case `/renew` reports as `1028`). |
| `Dna.DomainService:Domain:1028` | The renewal would push total registration past the longest term in the extension's `renewalPeriods`. Renew for fewer years. |
| `Dna.DomainService:Domain:10071` | Premium domain with `period` above 1. Premium names are one year at a time. |
| `Dna.DomainService:Domain:10072` | The registry's premium price changed since your search. **Nothing was charged.** Search again for the current price. |
| `Dna.DomainService:Domain:10049` | No price configured for this extension and period. Open a ticket. |
| `Dna.DomainService:Domain:10048` | No transfer price configured for that period. |
| `Dna.DomainService:Price:10001` | No pricing information for this extension, so a search cannot be priced. |

### Availability and status

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Domain:1026` | Already registered. Search first; consider transfer. |
| `Dna.DomainService:Domain:10016` | The domain's status does not permit this operation. Read `status` and `statusReason` from `/domains/info`. |
| `Dna.DomainService:Domain:1019` | An invalid status value in `statusIds`. |
| `Dna.DomainService:Domain:10017` | Registry search temporarily unavailable. Retry after a pause. |
| `Dna.Domainservice:Domain:10036` | More than 30 domains in one bulk search. Batch them. |
| `Dna.DomainService:Domain:10034` | Invalid `sorting` value. |

### Renewal

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Domain:10018` | Not in a renewable state — deleted, transferred out, or pending deletion. |
| `Dna.DomainService:Domain:10019` | Temporarily unavailable — for a renewal, a registry connection problem was recorded for this domain in the last three days. Retry later. |
| `Dna.DomainService:Domain:10020` | The registry already auto-renewed it and the expiry has moved. Re-read the domain. |
| `Dna.DomainService:Domain:10021` | Too early — this extension does not allow renewal this far ahead. |
| `Dna.DomainService:Domain:10051` | Renewed very recently and still inside the registry's grace window. Wait a few days. |
| `Dna.DomainService:Domain:10045` | A renewal prohibition is set at the registry. |
| `Dna.DomainService:Domain:10042` | Renewed at the registry but something failed afterwards. Check the expiry date before acting. |

### Transfer

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Domain:10008 / 10047` | Wrong authorisation code. Have the customer re-fetch it from their current registrar. |
| `Dna.DomainService:Domain:10026` | `authCode` missing. |
| `Dna.DomainService:Domain:10035` | Auth code length is outside this extension's limits. `details` gives the min and max. |
| `Dna.DomainService:Domain:10006` | Transfer lock active. The customer must unlock at their current registrar. |
| `Dna.DomainService:Domain:10031 / 10057` | **60-day rule.** Registered or transferred within the last 60 days. Registry policy — you can only wait. |
| `Dna.DomainService:Domain:10028` | You already have a transfer pending on this domain. |
| `Dna.DomainService:Domain:10029` | Another registrar's transfer is pending. Wait for it to resolve. |
| `Dna.DomainService:Domain:10024 / 10011` | Transfer not permitted for this domain, or not supported by this extension. |
| `Dna.DomainService:Domain:10025` | Transfer check not supported — skip it and transfer directly. (Different meaning on `/transfers/query`.) |
| `Dna.DomainService:Domain:10039` | The domain is available, not registered. Register it instead. |
| `Dna.DomainService:Domain:10027` | No transfer history at the registry. |
| `Dna.DomainService:Epp:2303` | The domain does not exist at the registry. |
| `Dna.DomainService:Domain:10040` | The authorisation code could not be changed. |

### Restore, forwarding, lock

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Domain:10043` | Not in the redemption period, so restore is impossible. Check `rgpStatues`. |
| `Dna.DomainService:Domain:10038` | No registrant contact on the domain. Open a ticket. |
| `Dna.DomainService:Domain:1017` | No forwarding configured on this domain. |
| `Dna.DomainService:Domain:1018` | `forwardType` could not be resolved to `Standard` or `Frame`. |
| `Dna.DomainService:Domain:1025` | A forward already exists. Delete it first. |
| `Dna.DomainService:Domain:10032` | Unlock refused because an ownership change is pending. |
| `Dna.DomainService:Tld:10001` | This extension does not support WHOIS privacy. |
| `Dna.DomainService:DomainSale:10007` | The domain is listed for sale and uses parking records. Cancel the listing before changing DNS or forwarding. |

### Documents

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Domain:10055` | The domain is not expecting documents. Check `status` and `statusReason`. |
| `Dna.DomainService:Domain:10061` | `documents` empty or missing. |
| `Dna.DomainService:Domain:10066` | An entry lacks `fileName` or `fileContent`. |
| `Dna.DomainService:Domain:10065` | Invalid `documentType`. |
| `Dna.DomainService:Domain:10062` | Format not allowed. PDF, DOC, DOCX, ODT, JPG, JPEG, PNG only. |
| `Dna.DomainService:Domain:10067` | Not valid Base64. **Usually a leftover `data:` prefix.** |
| `Dna.DomainService:Domain:10068` | The extension does not match the file's real format. `details` says what it actually is. |
| `Dna.DomainService:Domain:10069 / 10064` | A single file over 10 MB, or the request total over 50 MB. |
| `Dna.DomainService:Domain:10063` | More than 10 documents would be under review. |

## Contact errors

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Contact:10018` | **The most common contact error.** A role is missing. On `/domains/register` this usually means a `contactType` capitalisation problem — it must be exactly `Registrant`, `Admin`, `Billing` or `Tech`. |
| `Dna.DomainService:Contact:10022` | Two contacts resolved to the same role. |
| `Dna.DomainService:Contact:10005` | `contactType` could not be resolved. |
| `Dna.DomainService:Contact:10006 / 10007` | Contact information incomplete, or the handle list is empty. |
| `Dna.DomainService:Contact:10008` | The handle does not exist **in your account**. |
| `Dna.DomainService:Contact:10019` | Handle empty or malformed. |
| `Dna.DomainService:Contact:10020` | The handle is linked to a domain you do not own. Nothing was changed. |
| `Dna.DomainService:Contact:10021` | A contact attached to a domain cannot be deleted. |
| `Dna.DomainService:Contact:10026` | The handle is used by several domains in a way that cannot be re-pointed safely. Create a dedicated handle. |
| `Dna.DomainService:Contact:10011` | Invalid e-mail address. |
| `Dna.DomainService:Contact:10012` | **Invalid country.** Must be an ISO 3166-1 alpha-2 code — `GB` not `UK`, `TR` not `Turkey`. |
| `Dna.DomainService:Contact:10013` | Phone country code contains non-digits. **Remove the `+`.** |
| `Dna.DomainService:Contact:10014` | Phone number unusable after normalisation. |
| `Dna.DomainService:Contact:10017` | The phone country code does not match the selected country. |
| `Dna.DomainService:Contact:10023 / 10024` | First or last name became empty after invalid characters were removed. Letters only. |
| `Dna.DomainService:Contact:10025` | A required field is missing. The message names it. |
| `Dna.DomainService:Domain:10037` | The domain uses the trustee service; its contacts cannot be changed. |

### Verification

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Contact:Verification:10010` | **Important.** You are changing a name, surname or company but the contact's e-mail is unverified. Verify the e-mail first. |
| `Dna.DomainService:Contact:Verification:10008` | An ownership-change verification is already open. Let it finish. |
| `Dna.DomainService:Contact:Verification:10006` | Handle not found in your account. |
| `Dna.DomainService:Contact:Verification:10005` | No verification record. Usually means the extension is outside verification scope, or verification finished long ago. Treat as "nothing pending". |
| `Dna.DomainService:Contact:Verification:10003` | Already verified. Treat as success. |
| `Dna.DomainService:Contact:Verification:10002` | Inside the 1-minute re-send cooldown. The message says how long to wait. |
| `Dna.DomainService:Contact:Verification:10001` | Send limit reached. The customer likely has a mail-delivery problem. Open a ticket. |
| `Dna.DomainService:Contact:Verification:10007` | Too many e-mail changes in one verification chain. Open a ticket. |
| `Dna.DomainService:Contact:Verification:10009` | This verification is finalised and cannot be re-sent. |
| `Dna.DomainService:Contact:Verification:10004` | The e-mail could not be sent. Retry shortly. |

## Extra registry fields

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:TldAttribute:10001` | You sent a key this extension does not define. `details` lists them. Read valid keys from the catalogue. |
| `Dna.DomainService:TldAttribute:10002` | A required attribute is missing. `details` names it readably. |
| `Dna.DomainService:TldAttribute:10003` | A value failed validation. For identity numbers, `data.ValidationError` says which rule failed — length, format, repeated digits or checksum. |
| `Dna.DomainService:TldAttribute:10004` | This extension does not support internationalised names. |
| `Dna.DomainService:TldAttribute:10005` | Value longer than the attribute allows. |

## Trustee service

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Trustee:10006` | This extension **requires** the trustee service. Send `useTrusteeContact: true`. |
| `Dna.DomainService:Trustee:10002` | The trustee service is not available for this domain. Supply real contact details instead. |
| `Dna.DomainService:Trustee:10004` | This extension does not support the trustee service. |
| `Dna.DomainService:Trustee:10001` | No trustee price configured. Open a ticket. |
| `Dna.DomainService:Trustee:10003 / 10007 / 10008` | Trustee configuration problems on our side. Open a ticket. |

## Name server and host errors

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Dns:10022` | **Common.** Too few or too many name servers for this extension. Usually 2 to 13. |
| `Dna.DomainService:Dns:10013` | Duplicate entry in `nameServers`. |
| `Dna.DomainService:Dns:10005` | `nameServers` is empty. |
| `Dna.DomainService:Dns:10025` | The change would drop below the extension's minimum. |
| `Dna.DomainService:Dns:10003` | The name server or DNS record was not found. |
| `Dna.DomainService:Dns:10016` | A name server under this domain needs a glue IP. Create the host record first. |
| `Dna.DomainService:Dns:10019` | The host is not a subdomain of the domain. Most registries only accept glue for in-domain hosts. |
| `Dna.DomainService:Dns:10017` | Glue records are not allowed for this extension. |
| `Dna.DomainService:Dns:10018` | We could not determine how this extension models name servers. Open a ticket. |
| `Dna.DomainService:Dns:10021` | The host already exists on this domain. |
| `Dna.DomainService:Dns:10020 / 10004` | The host does not exist on this domain. |
| `Dna.DomainService:Dns:10023 / 10024` | The host cannot be deleted — it is still in use as a name server. Re-delegate first. |
| `Dna.DomainService:Dns:10007 / 10008` | Malformed IPv4 or IPv6 address. |
| `Dna.DomainService:Dns:10014` | `ipVersion` must be `v4` or `v6`. |
| `Dna.DomainService:Dns:10015` | Duplicate IP address in the request. |
| `Dna.DomainService:Dns:10026` | This extension does not accept IPv6 glue. Send only v4. |
| `Dna.DomainService:Dns:10012` | `hostName` is empty. |
| `Dna.DomainService:Domain:10070` | No DNS change is allowed while the domain is waiting for registry documents. |

## DNSSEC errors

| Code | Meaning and what to do |
| --- | --- |
| `Dna.DomainService:Dnssec:10005` | **The most common one.** The digest is not hexadecimal, or its length does not match the `digestType` you declared. SHA-1 is 40 characters, SHA-256 is 64, SHA-384 is 96. |
| `Dna.DomainService:Dnssec:10001` | This extension does not support DNSSEC. |
| `Dna.DomainService:Dnssec:10003` | Algorithm not permitted. Read `allowedAlgorithms` from `GET /dnssec`. |
| `Dna.DomainService:Dnssec:10004` | Digest type not permitted. Read `allowedDigestTypes`. |
| `Dna.DomainService:Dnssec:10002` | `keyTag` outside 0–65535. |
| `Dna.DomainService:Dnssec:10006` | That DS record already exists, or you sent it twice. **Often caused by resubmitting after `isPending: true`.** |
| `Dna.DomainService:Dnssec:10007` | Delete: no record matches all four fields. Copy them exactly from `GET /dnssec`. |
| `Dna.DomainService:Dnssec:10008` | Would exceed the maximum DS record count. Remove an old record first. |
| `Dna.DomainService:Dnssec:10010` | You are changing name servers while DNSSEC is active. Set `dnssecMode` to 1 or 2. |
| `Dna.DomainService:Dnssec:10011` | DS removal failed, so the name servers were not changed. Nothing was altered. |
| `Dna.DomainService:Dnssec:10012` | DS removal is queued for registry approval. Retry the name-server change afterwards. |
| `Dna.DomainService:Dnssec:10013` | The registry returned no DS record. Local records were preserved. Re-read the state. |

## DNS record errors

| Code | Meaning and what to do |
| --- | --- |
| `ZoneClient:10006` | The zone does not exist. Create the first record with `POST`. |
| `ZoneClient:10007` | No such record set, or no value matching what you sent. Read the zone and copy the value exactly. |
| `ZoneClient:10002` | An `A` record's value is not valid IPv4. |
| `ZoneClient:10003` | An `AAAA` record's value is not valid IPv6. |
| `ZoneClient:10010` | A `CNAME` or `MX` value is an IP address. These need host names. |
| `ZoneClient:10009` | An `MX` priority is not a number. The format is `10 mail.apiname.com`. |
| `ZoneClient:10004` | The record name is required and cannot start with `@`. A CNAME cannot sit at the apex — use `ALIAS`. |
| `ZoneClient:10005` | A `CAA` value is not three space-separated fields. `details` shows the format. |
| `ZoneClient:10011` | The record name does not belong to this zone. |
| `ZoneClient:10008` | The DNS server rejected the value's syntax. |
| `ZoneClient:10001` | The DNS service is temporarily unreachable. Retry shortly. |
| `Dna.DomainService:Zone:10001` | That exact value already exists in the set. Nothing was changed. |
| `ZoneClientValidationError` | A CNAME was sent without a `name`. |

## SSL errors

### Order and timing

| Code | Meaning and what to do |
| --- | --- |
| `Ssl:10026` | No certificate for this domain. Call `initialize` first. |
| `Ssl:10056 / Ssl:10077` | **The 7-day configuration window expired.** The fee is being refunded. Buy a new certificate. |
| `Ssl:10052` | A certificate with a different package is already awaiting configuration for this domain. |
| `Ssl:10013` | An active certificate already exists. Reissue or renew instead. |
| `Ssl:10027 / Ssl:10008 / Ssl:10041` | The certificate's status does not allow this operation. |
| `Ssl:10057` | Renewal is not open yet. The message gives the date. |
| `Ssl:10058 / Ssl:10059` | Already renewed, or not renewable. |
| `Ssl:10055` | The subscription has ended. Buy a new certificate. |
| `Ssl:10067` | The package is no longer on sale. |
| `Ssl:10003` | `packageCode` unknown. |

### CSR, names and configuration

| Code | Meaning and what to do |
| --- | --- |
| `Ssl:10040` | **Common.** The CSR's common name does not match `domainName`. Verify with `check-csr` before buying. |
| `Ssl:10004` | The CSR could not be decoded. Check the BEGIN/END lines. |
| `Ssl:10019` | Wildcard package but the CSR name does not start with `*.` |
| `Ssl:10015 / Ssl:10023` | `sanList` sent to a single-domain package, or missing on a multi-domain package. |
| `Ssl:10016 / Ssl:10022 / Ssl:10024` | `wildcardList` sent to a non-wildcard package, or missing on a wildcard package. |
| `Ssl:10017 / Ssl:10018 / Ssl:10032` | A wildcard or SAN name is invalid, or duplicates the main name. |
| `Ssl:10020 / Ssl:10021` | More than 255 SANs, or duplicates in the list. |
| `Ssl:10035 / Ssl:10030 / Ssl:10051` | The validation method is invalid, or not supported by this package or CA brand. |
| `Ssl:10037` | `webServerType` is not a valid value. |
| `Ssl:10014 / Ssl:10038` | `approverMail` malformed, or not on the approver list. |
| `Ssl:10010 / Ssl:10011 / Ssl:10012` | The `contact` object is missing or incomplete. |
| `Ssl:10001 / Ssl:10005` | Invalid domain name for a certificate. |

### Provider and lifecycle

| Code | Meaning and what to do |
| --- | --- |
| `Ssl:10053` | **Never retry.** Configuration has already been sent to the CA. Poll `check-status`. |
| `Ssl:10054` | **Never retry.** The outcome could not be verified. Open a ticket with the `certificateId`. |
| `Ssl:10048` | Not issued yet (or an invalid provider order — read the message). Keep polling. |
| `Ssl:10049` | The CA could not be reached, or a revoke failed. Read the message. |
| `Ssl:10050` | The CA rejected the request. Their explanation is in the message. |
| `Ssl:10006 / Ssl:10007` | Reissue is unsupported, or failed. |
| `Ssl:10031` | Certificate creation failed at the CA. |
| `Ssl:10070 / Ssl:10075 / Ssl:10076` | This package or operation is handled by our technical team. Open a support ticket. |
| `Ssl:10044 / Ssl:10046` | No price configured for this package. |

## Hosting errors

Hosting returns a plain English `message` without a code. Match on the message text.

| Message | Meaning and what to do |
| --- | --- |
| `Insufficient balance to purchase this hosting package.` | Top up and retry. |
| `The provided domain name is invalid.` | Fix `domainName`. |
| `Hosting not found.` | No matching record for the `serviceId` or `domainName`. |
| `You are not authorized to access this hosting.` | The record belongs to another reseller. |
| `Either serviceId or domainName must be provided.` | You sent neither. |
| `Provide only one of serviceId or domainName, not both.` | You sent both. |
| `No product is defined for package '{name}'.` | Configuration problem. Open a ticket. |
| `No price defined for package '{name}'.` | No price for your account on that package. Open a ticket. |
| `Token is required. / Token not recognized.` | Problem with the `token` on `/by-token`. |
| `Token was not recognized by the panel.` | The hosting panel rejected the token. |
| `No hosting account is available for this hosting.` | Provisioning never completed. Check `check-status`. |

## Validation errors

Requests that fail field validation return HTTP 400 with a `validationErrors` array rather than a single code. The `members` entry is prefixed with the contact role, so you can map it onto your form directly.

| Message pattern | What to fix |
| --- | --- |
| `{Role} first name is required.` | `firstName` missing on that role. |
| `{Role} first name must be at least 2 characters long.` | The name became empty or too short after non-letter characters were removed. |
| `{Role} 'company name' must be at least 2 characters long.` | `companyName` too short. Omit it entirely to have it auto-filled from the name. |
| `{Role} PhoneCountryCode must contain only digits (e.g., 90). Please do not use the '+' sign.` | **Remove the `+`.** |
| `{Role} EMail / Address / Phone / PostalCode / Country / City / State is required.` | That field is missing. `state` cannot be empty — repeat the city if the country has no states. |
| `domainName / privacyStatus / redirectAddress / forwardType field is missing` | Returned under the code `DnaValidationError`. The message names the field. |