Skip to main content
When a request fails, the API returns an error response with an HTTP status code and a JSON body describing the problem.

Error response format

All errors return both an error field and a message field:

Status codes

The fetch endpoint can also return 422 (page-level fetch failure: not_found, blocked, or unextractable) and 503 (temporarily unavailable — retry). See content retrieval error handling.
Causes: Missing q parameter, invalid parameter values, malformed JSON array in q.Example messages:
  • Missing required parameter: q
  • Invalid value for 'searchMode'
  • Invalid value for 'effort'. Must be one of: low, medium, high, max.
Fix: Check your query string parameters against the parameter reference.
Causes: Missing x-api-key header, invalid or revoked API key.Example messages:
  • Missing x-api-key header
  • Invalid API key
Fix: Verify your API key in the API Console. Make sure you’re passing it in the x-api-key header (not as a query parameter or in the Authorization header).
Cause: Your account has no remaining credits.Message: Your account has insufficient credits. Please add credits to continue.Fix: Add credits to your account.
Cause: Too many requests in the current time window.Message: Rate limit of N requests per second exceededFix: Back off and retry after the period specified in the Retry-After header. See rate limits for monitoring usage.
Cause: An unexpected error on our side.Fix: Retry with exponential backoff. If it persists, contact support.

Handling errors in code

Check the HTTP status code before parsing the response body:

Retry with exponential backoff

For transient errors (429, 500), retry with increasing delays:
Do not retry 400, 401, or 402 errors — these indicate problems that won’t resolve by retrying. Fix the request or account issue first.

Troubleshooting

Next steps

Rate limits

Rate limit headers and monitoring.

Authentication

API key management and security.