Guides
Errors
The error envelope, every code, and what to do about each.
Errors from execution requests use this shape. This example shows a request rejected because its start_url
points outside the connected website:
{ "error": { "code": "INVALID_START_URL", "message": "start_url must remain on the connected website origin." } }error.code is stable and meant for your logic. error.message is for logs and people and may change. The
OAuth token and revocation routes use the OAuth error format, with a string in error and an explanation in
error_description.
Codes
| Code | Status | What it means |
|---|---|---|
INVALID_EXECUTION | 400 | The prompt is missing or longer than 10,000 characters. |
INVALID_START_URL | 400 | start_url isn't on the connected website's origin. |
INVALID_OUTPUT_SCHEMA | 400 | The schema breaks a rule in Structured results. |
INVALID_IDEMPOTENCY_KEY | 400 | The key is empty or longer than 255 characters. |
INVALID_PAGINATION | 400 | limit is outside 1–50, or after isn't an execution id. |
INVALID_JSON, REQUEST_TOO_LARGE | 400, 413 | The body isn't JSON, or is over 64 KiB. |
CONNECTION_NOT_FOUND, EXECUTION_NOT_FOUND, NOT_FOUND | 404 | The token is unknown or revoked, or the resource doesn't exist or isn't yours. The response doesn't reveal whether an inaccessible resource exists. |
INSUFFICIENT_CREDITS | 402 | Your credit balance is below one credit. See Billing. |
CONNECTION_REAUTHORIZATION_REQUIRED | 409 | The user needs to sign in again. See Re-authorization. |
IDEMPOTENCY_KEY_REUSED | 409 | The key was used with a different body. |
INTERNAL_ERROR | 500 | Something unexpected. Retry once, then report it. |
OAuth codes
| Code | Status | What it means |
|---|---|---|
invalid_client | 401 | Unknown client_id, or a wrong secret. |
invalid_grant | 400 | The code is invalid, expired, or already used, redirect_uri doesn't match, or the PKCE verifier doesn't match. |
unsupported_grant_type | 400 | grant_type isn't authorization_code. |
invalid_request | 400 | The body couldn't be read. |
For execution request errors, log the route, error.code, and error.message. For OAuth errors, log the route,
error, and error_description. The 4xx codes are things your code or your user can fix; the 5xx codes are
things to retry and then report.
Next steps
A run that started and then failed reports its reason in terminal.status instead.
Handling failures covers each one.