Errors

Every error — whether produced by the service or by the API gateway in front of it — returns the same JSON envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Human-readable explanation of what went wrong.",
    "request_id": "5f3e1c2a-…"
  }
}

Field	Type	Description
code	string	Stable, machine-readable error code. Branch on this, not on message.
message	string	Human-readable explanation, safe to log or surface to operators.
request_id	string	Unique ID for this request. Quote it when reporting a problem.
details	array	Only present on validation_error — one entry per offending field (see below).

Error codes

Status	code	Meaning
400	invalid_json	Request body is not valid JSON. The message pinpoints the line and column where parsing failed.
403	INVALID_API_KEY / ACCESS_DENIED	Missing or invalid x-api-key header (generated by the gateway).
404	not_found	Unknown path. The message lists the available endpoints.
405	method_not_allowed	Method other than POST.
422	validation_error	Body failed validation — missing field, empty list, title too long, batch too large. See details.
429	THROTTLED / QUOTA_EXCEEDED	Rate limit or daily quota exceeded (generated by the gateway). Back off and retry.
500	internal_error	Unexpected service failure. Retry once; if it persists, report the request_id.

Gateway-generated codes (403, 429) are upper-case API Gateway response types; service-generated codes are lower-case. Treat any code you don’t recognise as non-retryable except 429 and 500.

Example — 422 validation error

{
  "error": {
    "code": "validation_error",
    "message": "Request body failed validation (titles[41]). See details.",
    "request_id": "5f3e1c2a-…",
    "details": [
      {
        "field": "titles[41]",
        "issue": "String should have at most 300 characters",
        "type": "string_too_long"
      }
    ]
  }
}

field identifies the offending input — for batch requests it includes the item index (titles[41]), so you can fix or drop just that item and resubmit.