Requests and responses

Request format

• POST, PUT, DELETE take a JSON body, with two exceptions noted in their sections (zone and some DNSSEC calls also take query-string parameters).
• GET takes query-string parameters.
• Field names are camelCase: domainName, authCode, nameServers.
• Domain names may be sent in Unicode or in punycode. örnek.com and xn--rnek-hra.com are the same domain to us.
• Dates are ISO 8601.
• Do not send fields you do not mean to set. For several fields, “absent” and “empty” mean different things — the field reference says so where it matters.

Response format

A successful call returns the endpoint’s JSON object. Some endpoints have nothing to return and answer with HTTP 204 and an empty body — that is success, not a problem. Each endpoint below states which it is.

Status	Meaning
200	Success, with a body.
202	Accepted — the work continues in the background. Only hosting creation returns this.
204	Success, no body.
400	The input was rejected — a malformed field, an invalid domain name or auth code. Field validation errors carry validationErrors.
401	Authentication problem. Plain text body.
402	Insufficient balance (Dna.DomainService:Deposit:10001).
403	A business rule refused the operation. Most error codes arrive with this status.
404	The domain, host, DNS record or forward does not exist or is not yours (Dna.DomainService:Domain:10007 and similar) — or the URL itself is wrong.
409	Conflict: the domain already exists or is already yours, a host already exists, a transfer lock is set or a transfer is already pending.
422	Domain name too short or too long.
429	More requests per second than your limit allows. See Rate limits.
500	Something broke on our side. Safe to retry once after a short pause; if it persists, open a ticket with your correlation ID.

Branch on the error code, not the status

Several error codes share a status, so the status alone does not tell you what happened. Read error.code from the body. A 404 with no error code means the URL was wrong; a 404 with Dna.DomainService:Domain:10007 means the domain does not exist or is not yours.