Responses & Errors

Success envelope

Successful responses return success: true and a data payload. List endpoints return an array; item endpoints return an object. Some endpoints add a meta object (for example the fields that were updated).

{
  "success": true,
  "data": {"id": 1000, "name": "example.com"},
  "meta": {"updated_fields": ["https", "default_cache_ttl"]}
}

Error envelope

Errors return success: false and an error object with a stable, machine-readable code, a human-readable message, and optionally a details object with field-level information.

{
  "success": false,
  "error": {
    "code": "unprocessable_entity",
    "message": "No fields could be updated.",
    "details": {"frobnicate": "Unknown or read-only field."}
  }
}

HTTP status codes

Status	Meaning
200	OK
201	Created
207	Multi-status (some purge patterns succeeded, some failed)
400	Bad request
401	Missing or invalid credentials
403	Authenticated but not permitted
404	Resource not found
405	Method not allowed
409	Conflict (for example, the resource already exists)
422	Validation failed
429	Rate limited
500	Internal error
502	Upstream failure (for example, the purge service)
503	Temporarily unavailable (maintenance / EPO)

Error codes

Code	When it occurs
missing_credentials	No API key was supplied.
invalid_key	The key is malformed or the secret does not match.
key_revoked	The key has been revoked.
key_expired	The key is past its expiry date.
key_disabled	The key has been disabled.
api_disabled	The account’s global API toggle is off.
account_locked	The account is locked.
ip_not_allowed	The request IP is not in the key’s allowlist.
read_only	The account is in read-only mode.
service_unavailable	The operation is temporarily disabled (EPO).
not_found	The requested resource does not exist.
conflict	The resource already exists or conflicts.
unprocessable_entity	The request body failed validation.
bad_request	The request could not be processed.
internal_error	An unexpected server error occurred.