Integration

Errors and limits

Check the HTTP status before reading a success response. API errors use an error object with a machine-readable code, a message, and a request ID.

Error response

Code
{
  "error": {
    "code": "content_not_available",
    "message": "An ending explanation is not available for this movie.",
    "request_id": "example-request-id"
  }
}

Validation errors can also include error.details, an array of { "field": "...", "message": "..." } objects. Use the status and code for application behavior; messages are intended to explain the problem.

Decide what to do

Status	Meaning	Action
`400`	Invalid parameters, path values, or cursor.	Correct the request. Restart pagination if the cursor expired.
`401`	Missing or invalid credentials.	Check the Bearer header and API key.
`403`	Access denied.	Check subscription status, payment, and remaining monthly allowance.
`404`	Resource, content section, or route not found.	Check the path and distinguish missing content from an unknown resource.
`429`	Request limit reached.	Wait for `Retry-After` before trying again.
`500` or `503`	Server or temporary availability problem.	Retry a small number of times with backoff.

An empty search is a 200 response with an empty data array. It is different from a 404 on a detail endpoint. All documented data operations use GET; check the method and URL if a route is not found.

Monthly allowance and burst limit

Free includes 100, Starter 5,000, and Pro 25,000 successful requests per monthly subscription period. Check your exact reset date and remaining allowance in My Subscriptions. Each successful page or content request counts as one request. Unsuccessful responses do not consume the monthly allowance.

An exhausted allowance blocks further access with 403; there are no automatic overage charges. Usage updates and quota enforcement can be briefly delayed, so do not rely on an exact cutoff for your own application budgets. Wait for the next period or change plan. A 403 can also indicate an inactive subscription or a payment problem.

A separate burst limit permits 60 requests per minute per consumer. Keys attached to the same consumer share that limit. This returns 429 rather than 403.

A rate-limited response includes Retry-After in seconds. Wait at least that long before another attempt. Coordinate workers that share credentials, and avoid launching large bursts of parallel requests.

Pagination requests and requests for separate content sections are separate API calls. Fetch only the sections your interface needs.

Retry responsibly

For temporary server failures, use exponential backoff with a little random jitter and a maximum number of attempts. Give each request a timeout. Do not automatically retry invalid parameters, rejected credentials, or unavailable content.

Record the HTTP status, error.code, request ID, timestamp, and endpoint when troubleshooting. Redact authorization headers and API keys from logs and shared reports.

Next: JavaScript and Python examples →

Last modified on October 19, 2026

Pagination and response conventions Code examples