Golzak DevelopersGolzak Domains API · v1

Errors

Errors use the problem-details format of RFC 9457, media type application/problem+json, with one extra member, code:

{
  "type": "https://developers.golzak.com/domains/v1/errors#insufficient_credit",
  "title": "Insufficient credit",
  "status": 402,
  "code": "insufficient_credit",
  "detail": "Top up your Golzak account credit, then retry with a new Idempotency-Key. Nothing was ordered.",
  "request_id": "req_01JA7X3M9Q2W8E5R6T7Y8U9I0P"
}

Branch on code. Codes are stable for the whole of v1: never renamed or removed, only added. A code you do not know is not a bug: handle it by its HTTP status (4xx: show detail, do not retry; 5xx: retry with the same Idempotency-Key). The same goes for other lists that v1 may extend (domain statuses, pending_reason, operation types, webhook event types): treat an unknown value as unknown, never as an error. title and detail are for humans and can change. validation_failed adds errors[], one entry per broken rule, each with field, code and message.

Retry rule in one line: 429, 500, 502 and network timeouts → retry with the same Idempotency-Key; every other error → do not retry as is; fix the cause, and send a new key for the corrected request.

Order of checks on a POST

A registration is checked in this order; the first failing step answers, and nothing is ordered:

  1. API key and IP (401, 403), rate limit (429), Idempotency-Key present (428).
  2. Request syntax (400 invalid_request) and host-name syntax (400 invalid_domain_name).
  3. Extension (422 tld_manual_only, tld_not_supported), then one label plus the extension (400 invalid_domain_name).
  4. Body rules, holder rules, years, nameservers (422 validation_failed, all broken rules at once), then 422 holder_is_reseller.
  5. Availability (409 domain_not_available).
  6. Credit (402 insufficient_credit), then daily cap (403 daily_spend_cap_reached).

All codes

HTTP code Meaning What to do Retry?
400 invalid_request Malformed JSON, unknown field, bad query parameter. Fix the request. No
400 invalid_domain_name Not a lower-case ASCII host name, or not exactly one label plus an accepted extension (e.g. a.b.ma, or a bare co.ma). Send e.g. example.ma, example.co.ma. No
401 invalid_api_key Key missing, unknown or revoked. Check the Authorization header. No
403 ip_not_allowed The key is limited to other IP addresses. Call from an allowed address, or ask Golzak. No
403 account_suspended Your reseller account is suspended. Contact Golzak. No
403 daily_spend_cap_reached The order would exceed the key's daily cap. Nothing ordered. Wait for cap_resets_at, or ask Golzak. After cap_resets_at, new key
402 insufficient_credit Credit does not cover the charge. Nothing ordered. Top up; retry with a new key. After top-up, new key
404 route_not_found The method and path are not an endpoint of the Domains API v1. Check the path against the reference; paths start with /domains/v1. No
404 domain_not_found No such domain in your account. Check the name; list with GET /domains. No
404 operation_not_found No such operation in your account. Check the ID. No
409 domain_not_available The name is already registered. Nothing ordered. Suggest another name. No
409 operation_in_progress Another operation is still running on this domain. Wait for it to end. After it ends
409 domain_status_prohibits The domain's state forbids this change (e.g. under ANRT review, expired). Wait, or contact Golzak. When the status allows
409 idempotency_key_in_use A call with this key is still running. Retry the same call shortly. Yes, same key, after a few seconds
422 idempotency_key_reused Same key, different body. Use a new key for a new action. No (new key for a new action)
428 idempotency_key_required POST without Idempotency-Key. Send one (a UUID). Yes, with a key
422 tld_not_supported This API version does not offer the extension. In v1: .ma, .co.ma, .net.ma, .org.ma (GET /prices lists them). No
422 tld_manual_only .ac.ma, .gov.ma, .press.ma: handled by hand. Contact Golzak. No
422 validation_failed One or more rules broken; see errors[]. Nothing ordered. Fix every listed field. After fixing, new key
422 holder_is_reseller The holder is your own company. Register in your client's name. No
422 registry_refused (In an operation's error.) ANRT refused the name. Tell your client; the charge is refunded. No
422 transfer_not_completed (In an operation's error.) The transfer did not complete within 10 business days. Check the lock and the EPP code with the current registrar; order again. The charge is refunded. New order, new key
502 registry_error The registry rejected the command (e.g. bad nameserver). Read detail; fix and retry with a new key. After fixing, new key
429 rate_limited Too many requests. Wait Retry-After seconds. Yes, after Retry-After, same key
502 upstream_unavailable Golzak's billing system or the registry did not answer. Retry with the same key. Yes, same key
503 orders_disabled Orders are switched off for a while (maintenance or an incident); reads and dry runs still work. Nothing was ordered. Retry later. Yes, same key, later
500 internal_error Bug on Golzak's side. Retry with the same key; report the request_id. Yes, same key

Field error codes in validation_failed

errors[].code Meaning
required The field is missing or empty.
invalid_value Not one of the allowed values (e.g. holder.type).
invalid_format Wrong format (phone, country, host name, e-mail), or a control character in text.
too_long Longer than the field's limit (255 characters for most text fields).
years_not_offered years is not in your price table for this operation.
exceeds_max_validity The name would be valid for more than 5 years from today (ANRT decision 02/2024 art. 33.1).
too_few / too_many Nameserver count outside 2 to 5.
duplicate The same nameserver twice.

The holder-specific messages are listed in Holder rules.