API errors, limits and retries

Most of what makes an API client reliable is how it behaves when a request does not succeed.

The envelope

Every response, success or failure, has the same outer shape:

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { ... } }

Branch on ok, not on the status code alone. The code tells you the class of problem; the error object names the specific one.

Status codes

The pattern worth internalising: only 429 and 5xx are worth retrying. Everything else will fail identically however many times you send it, and a client that retries a 400 in a loop is a client that gets rate limited for no reason.

Rate limiting

Requests are counted per key, per minute. The default allowance is 120 requests a minute; exceed it and you get 429.

When you do:

1. Wait before retrying. Immediately re-sending is what turns a brief limit into a sustained one.
2. Back off exponentially — a second, then two, then four — rather than a fixed interval.
3. Add jitter if several workers share a key, or they will all retry in step and hit the limit together.

Better still, do not reach it. Most clients that get rate limited are polling for something that rarely changes. List a zone's records once and work from that, rather than fetching before every write.

Failures that are not the API's

Two worth separating out, because the fix is elsewhere:

A plan limit. 422 on creating a zone or a record type usually means the plan does not allow it — not a bug in the request. The API enforces exactly what the portal does.

A validation rule. A CNAME at the apex, an MX pointing at an IP, a hostname that is an IP: refused, because each produces a record resolvers reject. The error says which rule; the record types article says why.

Designing for the boring cases

• Make writes idempotent where you can. Fetch, compare, and write only if different. It costs one read and removes a whole class of duplicate-record bug.
• Log the error object, not just the code. 400 on its own tells a future reader nothing.
• Fail loudly on 401 and 403. A revoked key produces those on every request, and a client that swallows them looks like it is working while doing nothing.
• Do not hard-code the base URL. It follows the panel's hostname — see getting started with the API.

Related

• API keys
• Zones through the API
• Records through the API

Last reviewed 2026-09-16.