REST API

Errors

All errors return a consistent JSON envelope and an appropriate HTTP status. Use code for branching, message for humans.

Envelope

json

{
  "error": {
    "code": "string_error_code",
    "message": "Human-readable description."
  }
}

Status	Code	Meaning
400	`invalid_request`	Validation failed. Body or params are malformed.
400	`invalid_source`	A URL passed as content source is unreachable or invalid.
401	`missing_api_key`	No API key provided.
401	`invalid_api_key`	API key format invalid, not found, or revoked.
403	`insufficient_scope`	Key is valid but doesn't carry the required scope.
404	`not_found`	Resource doesn't exist (or you don't have access to it).
413	`payload_too_large`	Request body exceeded the limit (~128 KB).
415	`unsupported_media_type`	Content-Type wasn't `application/json`.
429	`rate_limited`	Hit the per-minute or per-day cap. Honor `Retry-After`.
500	`internal_error`	Server failure. Retry idempotently or contact support.
502	`generation_failed`	Content generation failed downstream. Retryable.
502	`publish_failed`	Publishing to the CDN failed. Retryable.
502	`delete_failed`	Removing content from the CDN failed. Retryable.

GET and DELETE are idempotent. POST and PATCH are not — retry only for 5xx and 429, never for 4xx (other than 429).

For 400 invalid_request, the message field will name the offending field, e.g.:

json

{ "error": { "code": "invalid_request", "message": "title must be 120 characters or fewer." } }

Don't pattern-match on message — it may be revised. Branch on code.