Errors

Distinguish Unkey Gateway failures from CinemaData application failures.

Error bodies use a stable envelope:

{
  "error": {
    "code": "entitlement_required",
    "message": "An active CinemaData subscription is required",
    "requestId": "request-id"
  }
}

Gateway errors

These happen before the request reaches CinemaData:

Status	Meaning
`401`	The API key is missing, malformed, revoked, or invalid.
`429`	The Unkey request limit has been exceeded.

Application errors

Status	Code	Meaning
`400`	`bad_request`	Query parameters or a cursor are invalid.
`403`	`entitlement_required`	The organization has no active paid-through subscription.
`404`	`not_found`	The route or requested record does not exist.
`503`	`database_unavailable`	Entitlement or cinema data could not be checked safely. Retry with backoff.

The API fails closed: it does not return commercial data when identity, billing, or the database cannot be verified.