Errors
Handle stable public error codes and request IDs.
Errors have one public JSON shape. Database messages, stack traces, and internal implementation details are not returned.
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request parameters are invalid.",
"request_id": "req_01J7EXAMPLE"
}
}Error codes
| Status | Code | Meaning |
|---|---|---|
400 | VALIDATION_ERROR | A query or path parameter is missing, unknown, malformed, or outside its range. |
401 | MISSING_API_KEY | No API key was sent. |
401 | INVALID_API_KEY | The key scheme, format, or lookup failed. |
403 | API_KEY_DISABLED | The key exists but is inactive. |
404 | TITLE_NOT_FOUND | No title matches the supplied title ID. |
429 | RATE_LIMITED | The minute throttle rejected the request. |
429 | MONTHLY_QUOTA_EXCEEDED | The key exhausted its monthly policy. |
404 | ROUTE_NOT_FOUND | No route matches the request. |
500 | INTERNAL_ERROR | An unexpected internal error occurred. |
Validation behavior
Query objects are strict. Unknown parameters, including the obsolete cursor parameter, return VALIDATION_ERROR. Most validation failures use the generic message. Invalid title IDs use the specific message The IMDb ID must match ^tt\d+$. Search text that contains no letters or numbers uses The search query must contain letters or numbers.
Request IDs
Every response includes X-Request-Id, and every JSON envelope repeats it in meta.request_id or error.request_id.
You may supply X-Request-Id. The server accepts it only when it is no longer than 128 characters and contains letters, digits, ., _, or -. Otherwise the server generates a UUID.
Handling failures
Branch on the HTTP status first, then on the stable error.code. Show the public message when useful, log the request ID, and avoid retrying validation or authentication errors without changing the request.