Error Handling
Learn how to handle errors returned by the EdgeDNS API.
Error Response Format
REST analysis errors use this JSON structure. Account and watch routes can omit request_id or return additional success fields:
{
"error": {
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid or expired.",
"details": { }
},
"request_id": "req_abc123"
}MCP tool failures are returned as tool results with isError=true and a text message; they do not necessarily produce an HTTP 4xx or 5xx at the MCP transport. For REST, the details object is optional and provides additional context for specific error types (e.g., the required tier for a TIER_RESTRICTION error).
HTTP Status Codes
| Status Code | Description |
|---|---|
| 200 | Success - request completed successfully |
| 400 | Bad Request - invalid parameters or domain format |
| 401 | Unauthorized - invalid, expired, or missing API key |
| 402 | Payment Required - subscription payment needed |
| 403 | Forbidden - insufficient permissions or tier restriction |
| 404 | Not Found - resource does not exist |
| 409 | Conflict - duplicate resource or conflicting state |
| 413 | Payload Too Large - request body exceeds the route limit |
| 429 | Too Many Requests - rate limit or quota exceeded |
| 500 | Internal Server Error - something went wrong |
| 502 | Bad Gateway - upstream service returned an invalid response |
| 503 | Service Unavailable - temporary outage or circuit breaker open |
| 504 | Gateway Timeout - upstream service did not respond in time |
Error Codes
Authentication (401)
AUTHENTICATION_REQUIRED- No API key provided in the requestINVALID_API_KEY- The API key format is invalid, the key does not exist, or it is inactive/revokedAPI_KEY_EXPIRED- The API key has passed its expiration date
Authorization (403)
FORBIDDEN- Required key permission or organization access is missingTIER_RESTRICTION- Endpoint requires a higher tier than your current planIP_NOT_ALLOWED- Request IP is not in the key's allowlistSUBSCRIPTION_INACTIVE- Your subscription is expired or canceled
Validation (400)
VALIDATION_ERROR- Input validation failed (check details for specifics)MISSING_PARAMETER- A required parameter was not providedINVALID_DOMAIN- The domain format is invalidINVALID_IP- The IP address format is invalid
Rate Limiting (429)
RATE_LIMIT_EXCEEDED- Too many requests in the current window. CheckRetry-Afterheader.QUOTA_EXCEEDED- A monthly request allowance or an endpoint quota has been reached. Wait for reset or change the allowance; short retries do not restore quota.
Server Errors (500-504)
EXTERNAL_SERVICE_ERROR- An upstream service (DNS resolver, RDAP, etc.) returned an errorTIMEOUT- An upstream service did not respond in timeCIRCUIT_OPEN- Service temporarily unavailable due to repeated upstream failuresINTERNAL_ERROR- Unexpected server error. Contact support if persistent.
Retry strategy
Correct invalid inputs, credentials, permissions, and subscription problems before retrying 4xx responses. For RATE_LIMIT_EXCEEDED, honor Retry-After with bounded backoff. For QUOTA_EXCEEDED, inspect the quota and its reset instead of retrying immediately. Retry transient 502–504 failures with bounded backoff and jitter. Recheck resource state before retrying a write whose outcome is unknown. Error messages for server failures are intentionally generic; use error.code and the request ID for diagnosis.
Need Help?
For a persistent error, include the request_id, endpoint, and approximate request time when contacting support. Keep API keys out of support messages.