Error Handling

Only one non-200 response is defined in the current OpenAPI: domain registration may return HTTP 400 with an error object when the domain already exists.

{
  "error": "Registrar Error: \nObject exists; Domain is: newdomain.test.ly requested by client: registrar_test"
}

Error Reference

Scenario	HTTP status	Response format	Retry guidance	Status
Missing username	VALIDATION REQUIRED	VALIDATION REQUIRED	No; correct credentials first.	Needs validation
Invalid token	VALIDATION REQUIRED	VALIDATION REQUIRED	Regenerate using the verified algorithm.	Needs validation
Expired token	VALIDATION REQUIRED	VALIDATION REQUIRED	Regenerate only after expiry behavior is confirmed.	Needs validation
Invalid parameter	VALIDATION REQUIRED	VALIDATION REQUIRED	No; correct the request first.	Needs validation
Domain unavailable during registration	400 for the published “Object exists” example	{ "error": "Registrar Error: ..." }	No; recheck availability and domain state.	Partial
Unsupported TLD	VALIDATION REQUIRED	VALIDATION REQUIRED	No; confirm TLD support first.	Needs validation
Insufficient credit	VALIDATION REQUIRED	VALIDATION REQUIRED	No; fund or reconcile the account first.	Needs validation
Registry rejection	VALIDATION REQUIRED	VALIDATION REQUIRED	Depends on the verified rejection type.	Needs validation
Registry timeout	VALIDATION REQUIRED	VALIDATION REQUIRED	Conditional; verify transaction state first.	Needs validation
Rate limit	VALIDATION REQUIRED	VALIDATION REQUIRED	Retry later only after rate-limit behavior is confirmed.	Needs validation
Server error	VALIDATION REQUIRED	VALIDATION REQUIRED	Conditional; verify transaction state first.	Needs validation

Safe Failure Handling

• Parse the HTTP status and raw JSON shape separately; do not assume every error contains error.
• Keep sanitized request/response details and timestamps for support, excluding credentials and EPP codes.
• Do not automatically retry registration, renewal, contact, nameserver, glue, lock, sync, or EPP operations until their idempotency is documented.
• Never retry a non-idempotent write operation blindly. Verify the previous transaction state first where financial or domain state may have changed.
• Safe retry behavior must be confirmed endpoint by endpoint.
• Never log the API key, generated token, or EPP code.