Error response format
All errors return both anerror 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.
400 — Bad request
400 — Bad request
Causes: Missing
q parameter, invalid parameter values, malformed JSON array in q.Example messages:Missing required parameter: qInvalid value for 'searchMode'Invalid value for 'effort'. Must be one of: low, medium, high, max.
402 — Insufficient credits
402 — Insufficient credits
Cause: Your account has no remaining credits.Message:
Your account has insufficient credits. Please add credits to continue.Fix: Add credits to your account.429 — Rate limit exceeded
429 — Rate limit exceeded
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.500 — Internal server error
500 — Internal server error
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:
Troubleshooting
Next steps
Rate limits
Rate limit headers and monitoring.
Authentication
API key management and security.

