Errors

Every error has the same shape. code is stable; hint is written for AI agents and says what to do or ask next.

json

{
  "error": {
    "code": "contact_required",
    "message": "A registrant contact is needed to register a domain",
    "hint": "Ask the user for the domain owner's details (first_name, last_name, email, phone, address1, city, state, postcode, country) and pass them as `contact`. They're saved for next time.",
    "required_fields": ["first_name", "last_name", "email", "phone", "address1", "city", "state", "postcode", "country"]
  }
}

Code	HTTP	Meaning and fix
`unauthorized`	401	Missing, wrong or revoked API key.
`insufficient_scope`	403	The assistant connection lacks a permission. Reconnect and approve it.
`validation_error`	400	Fields are missing or wrong. issues lists each one with its path.
`invalid_json`	400	The body isn't JSON.
`invalid_domain`	400	Not a valid domain name. Letters, numbers and hyphens, up to 63 characters per label.
`unsupported_tld`	400	We don't sell that extension. Check GET /prices.
`lock_not_supported`	400	.au domains have no transfer lock.
`not_registered`	409	Transfer asked for a domain nobody has registered. Register it instead.
`already_in_account`	409	The domain is already with Plonki.
`transfer_not_possible`	409	The registry won't accept the transfer: wrong code, still locked, or registered or moved in the last 60 days. message says which.
`invalid_query`	400	Search needs q or domains.
`invalid_years`	400	The term is outside that extension's min_years and max_years.
`contact_required`	400	No owner details yet. Send contact once; it's saved.
`au_eligibility_required`	400	.au names need au_eligibility with an ABN or ACN. See the .com.au guide.
`invalid_nameservers`	400	Give at least two nameservers, or an empty list for Plonki DNS.
`invalid_amount`	400	Top-ups are A$10 to A$10,000, in cents.
`insufficient_balance`	402	Only with payment: "balance". Top up, or use payment: "auto" for a checkout link.
`not_found`	404	No such domain, order or contact in this account and mode.
`domain_unavailable`	409	Someone has it. Try suggest_domains.
`price_changed`	409	The live price is above max_price. Confirm the new amount (in amount) and retry.
`dns_not_hosted`	409	The domain uses external nameservers. Edit DNS there, or switch back with an empty nameserver list.
`rate_limited`	429	Too many requests. Wait a minute. See Limits and retries.
`registry_error`	502	The registry refused the request; message has its reason.
`registry_unreachable`	502	The registry didn't answer. Safe to retry with the same idempotency key.
`pricing_unavailable`	503	Prices are briefly unavailable. Retry shortly.
`payments_unconfigured`	503	Card payments aren't switched on. Use your balance.
`internal_error`	500	Our fault. Retry with the same idempotency key; contact support if it persists.