Read both the HTTP status and the structured response when a Domain Nexus request fails. An authentication problem, a validation error and a pending provider operation need different recovery actions.
IN THIS ARTICLE
01 Capture useful diagnostic details
Record the request method, v2 route, timestamp and returned request or support identifier. Keep the machine-readable error code and detail. Redact API keys, HMAC secrets, EPP codes and personal contact values before storing or sharing diagnostics.
| Status | What to investigate |
|---|---|
| 400 or 422 | JSON, required fields, identifier format and operation-specific validation |
| 401 | Credential method, key state, signature and clock |
| 403 | Scope, account policy, ownership, source network and enabled service |
| 404 | Correct route and resource visible to the authenticated account |
| 409 or 412 | Conflicting operation, idempotency review or stale version |
| 429 | Rate or account quota; follow the returned retry guidance |
| 503 | Maintenance or an unavailable dependency |
How do I investigate a timeout without repeating a paid operation?
A 202 response records accepted work. Read the returned operation or job before reporting success to your customer. For domains, GET /v2/operations/{operationId} and the domain's operation history provide the relevant state.
When logs access is permitted, GET /v2/request/{requestId} can return owned request evidence. The reseller portal's API logs and Activity log also help connect an integration failure with the business operation.
02 Correct the cause
For a 403, compare effective permissions with the route's required scope. Do not try another customer's identifier or broader credentials as a workaround. For a stale version, reread the resource and review your intended edit against the new state before submitting it.
For an idempotency conflict, preserve the original key and inspect the existing operation. For rate limiting, reduce concurrency and wait according to the response. Immediate repeated requests can extend the problem.
03 Escalate with evidence
If the provider outcome remains uncertain, send support the domain, operation reference, request ID, time and redacted error. Explain whether your system retried and whether it used the same idempotency key. This helps support reconcile the request without creating another paid operation.
Keep customer-facing messages accurate. An error can explain that work is pending or needs review without disclosing raw stack traces or confidential upstream account details.