# Requests and responses

> How to format requests, what each HTTP status means, and why you should branch on the error code rather than the status.

## 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](https://www.domainnameapi.com/docs/getting-started/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. |

:::note[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.
:::