Reference

Troubleshooting

The problems people hit most, what they mean and how to fix them. Every error also carries a message and usually a fix: read those first.

Errors from the API

You get	Why	Fix
`401 signed_out`	The request had no Authorization header, so the API treated it as a signed-out dashboard visitor.	Send `Authorization: Bearer itk_live_…`. Check the environment variable is actually set where the code runs.
`401 invalid_key`	The header isn’t “Bearer <key>”, or the key is mistyped, revoked or expired.	Copy the key again (it’s shown only once; make a new one if you lost it). No quotes or spaces around it.
`403 email_unverified`	Free subdomains, API keys and buying need a confirmed email (for a key: its creator’s).	Open the link Itoka emailed you, or ask for a new one in Settings.
`403 two_factor_required`	Creating API keys needs two-factor authentication.	Turn it on in Settings, then make the key.
`403 forbidden`	The key lacks a permission or the zone (the message names which), or the endpoint is dashboard-only.	Make a key with that permission, or pick the zone when creating it.
`404 zone_not_found`	The zone isn’t in your account, isn’t shared with you, or isn’t covered by the key.	Check the spelling. A zone a teammate shared with you must be picked by name on your key; “All your zones” covers only zones you own.
`403 bad_origin`	A browser on another website sent the request. The API only accepts browsers from the Itoka dashboard.	Call the API from your backend or a serverless function, never from frontend code (it would expose your key too). See Recipes.
`415 bad_request`	A request with a body didn’t say it was JSON.	Add `Content-Type: application/json`.
`400 bad_request`	The body isn’t valid JSON, or has a field the endpoint doesn’t know.	Records go inside `{"record": {…}}`; check field names against the guide.
`422 invalid_record`	The record breaks a rule (CNAME at @, an IP where a hostname belongs…).	Read `fix`. For a site on your subdomain's apex use an A record, not a CNAME. See DNS records.
`409 record_changed`	The record was changed or deleted since you read it; its id changes when it changes.	Read the zone again and use the new id, or use records.upsert in the SDK.
`409 zone_exists`	That name (or free subdomain) is already on Itoka.	Pick another name.
`429 rate_limited`	Over a limit, e.g. 300 requests a minute per key.	Wait `Retry-After` seconds and slow down. Cache what you read instead of polling. See Errors and limits.
`429 busy`	Another change to the same zone is being written.	Retry after `Retry-After` (5 seconds). Send a zone's changes one after another, not all at once.

My site doesn't load

On a .dev name, the browser refuses plain http. Every .dev site must serve HTTPS. Add the domain in your host (Vercel, Netlify, Render) so it issues a certificate, or put Caddy in front of your server.
Check what Itoka serves: dig +short yourteam.itoka.dev @ns1.itoka.ng. If that's right but your machine still sees the old answer, a resolver is holding it until its TTL runs out. GET /zones/{zone}/propagation shows what public resolvers see.
The host says the domain isn't configured. Add the custom domain in the host's dashboard as well; DNS alone isn't enough for it to serve your site.

My own domain isn't live

After verifying, change the nameservers at your registrar to ns1.itoka.ng and ns2.itoka.ng, and remove any others. The zone page shows when the registry and the parent zone have picked it up.
A domain you bought through Itoka needs nothing: it already uses Itoka's nameservers, and the registry publishes new names within minutes (some extensions take longer).

Still stuck

Email hello@itoka.ng with your account email, the request you sent (without the key) and the full error.