Errors

Errors use RFC 9457 problem details with a stable machine-readable code.

Format

Every error has Content-Type: application/problem+json. Branch on code (stable) rather than on title or detail (human text that may change). type links to the matching section below, and request_id equals the X-Request-Id header — include it when you contact support.

Example

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
X-Request-Id: 5f0c8d3e-4b7a-4f43-9a51-2a8c4f3f9b10

{
  "type": "https://hexascore.app/docs/errors#bad_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "One or more query parameters are invalid.",
  "code": "bad_request",
  "request_id": "5f0c8d3e-4b7a-4f43-9a51-2a8c4f3f9b10",
  "errors": [{ "path": "limit", "message": "Your plan allows at most 10 results per page." }]
}

Codes

400 bad_request

Invalid request

When: A query parameter is unknown or out of range, the cursor was tampered with or belongs to another query, or limit is above your plan's page size (10 on Free). errors lists each problem with its path.
What to do: Fix the listed parameters. Not counted against your quota when the parameters fail validation.

401 unauthorized

Missing or invalid API key

When: No Authorization: Bearer header, a malformed key, or a key that does not exist or was revoked.
What to do: Check the header and the key at /profile/api. Never retried automatically.

402 payment_required

Quota exhausted

When: The quota is exhausted: the 100 lifetime requests on Free, or the monthly quota plus prepaid credits on paid plans. The body includes plan and limit.
What to do: Upgrade or buy credits at /pricing. Paid quotas reset on the 1st of each month (UTC).

403 forbidden

Forbidden

When: The account that owns the key is suspended.
What to do: Contact us through /contact with the request_id.

404 not_found

Not found

When: Unknown item id, an id that belongs to another type (e.g. a game id under /movies), an unknown type path, or no match for /lookup.
What to do: Check the id and the type. Lookups require an exact id (e.g. tt0111161).

429 rate_limited

Too many requests

When: More requests per second than your plan allows. The Retry-After header says how many seconds to wait. Not counted against your quota.
What to do: Wait Retry-After seconds and retry; space out bursts or upgrade for a higher rate.

500 internal_error

Internal error

When: Something failed on our side. The request is refunded to your quota.
What to do: Retry with exponential backoff. If it persists, send us the request_id.

503 service_unavailable

Service unavailable

When: A dependency is temporarily down. Comes with Retry-After.
What to do: Retry after the indicated delay.

Retries

Retry only 429, 500 and 503, honouring Retry-After when present and backing off exponentially otherwise. Every endpoint is a read-only GET, so retries are always safe.