Skip to main content

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 CodeDescription
200Success - request completed successfully
400Bad Request - invalid parameters or domain format
401Unauthorized - invalid, expired, or missing API key
402Payment Required - subscription payment needed
403Forbidden - insufficient permissions or tier restriction
404Not Found - resource does not exist
409Conflict - duplicate resource or conflicting state
413Payload Too Large - request body exceeds the route limit
429Too Many Requests - rate limit or quota exceeded
500Internal Server Error - something went wrong
502Bad Gateway - upstream service returned an invalid response
503Service Unavailable - temporary outage or circuit breaker open
504Gateway Timeout - upstream service did not respond in time

Error Codes

Authentication (401)

  • AUTHENTICATION_REQUIRED- No API key provided in the request
  • INVALID_API_KEY- The API key format is invalid, the key does not exist, or it is inactive/revoked
  • API_KEY_EXPIRED- The API key has passed its expiration date

Authorization (403)

  • FORBIDDEN- Required key permission or organization access is missing
  • TIER_RESTRICTION- Endpoint requires a higher tier than your current plan
  • IP_NOT_ALLOWED- Request IP is not in the key's allowlist
  • SUBSCRIPTION_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 provided
  • INVALID_DOMAIN- The domain format is invalid
  • INVALID_IP- The IP address format is invalid

Rate Limiting (429)

  • RATE_LIMIT_EXCEEDED- Too many requests in the current window. Check Retry-After header.
  • 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 error
  • TIMEOUT- An upstream service did not respond in time
  • CIRCUIT_OPEN- Service temporarily unavailable due to repeated upstream failures
  • INTERNAL_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.

Error handling — Status codes & retry strategy | EdgeDNS