DomainsDocsSign in
Reference

Errors and limits

Every error has the same shape, says what went wrong, and usually how to fix it.

Any non-2xx response
{
  "error": {
    "code": "invalid_record",
    "message": "MX needs a hostname, not an IP address.",
    "reason": "Mail servers won't deliver to 159.195.40.229.",
    "fix": "enter the mail server's name, for example mx.zoho.com.",
    "field": "value"
  }
}

Branch on code. Show message, then reason and fix when present; they're written for people. field names the request field it's about. Records problems can carry an action: a one-click fix.

Status codes

StatusMeansSome codes
400The body isn’t valid JSON, has a field the endpoint doesn’t know, or is over 1 MB.bad_request
401No Authorization header (signed_out), or the key is wrong, revoked or expired.signed_out, invalid_key
403The key lacks a permission or the zone; the email isn’t confirmed; the endpoint is dashboard-only; or a browser on another site sent it.forbidden, email_unverified, bad_origin
404Not found, or not yours. Out-of-scope zones and domains are 404 too.zone_not_found
409It conflicts with the current state.record_changed, zone_exists, unverified_zone, quote_expired, suspended
415A request with a body didn’t send Content-Type: application/json.bad_request
422The input breaks a rule; field says which.invalid_record, invalid_zone_name, invalid_subdomain, invalid_promo_code
429Too many requests. Wait Retry-After seconds.rate_limited, busy
5xxSomething failed on Itoka’s side, or a feature isn’t switched on.sales_unavailable

Limits

WhatLimit
Requests per API key300 a minute
Orders per API key20 an hour
Domain searches30 a minute per IP address
Promo codes tried10 a minute per account
Webhook test and redeliver10 a minute per account (together)
Propagation checks2 different checks at a time per account
Import scans1 at a time per account
Delegation checks1 every 5 seconds per zone
Domains waiting for verification20 per account
Free subdomains3 per account
Webhook endpoints10 per account
TTL60 to 604800 seconds; Auto is 1800

Over a limit, the API answers 429; most limits also send Retry-After (seconds). There are no X-RateLimit-* headers. Lists aren't paginated: they return everything (webhook deliveries, the latest 100).

Conventions

  • Lists are always arrays ([] when empty), never null.
  • Money is in kobo: ₦19,000 is 1900000.
  • Times are RFC 3339 in UTC: 2026-10-14T16:33:33Z.
  • Names are lower case without a trailing dot; record names are relative to the zone, with @ for the apex.
PreviousAPI reference