Responses & errors
Every answer is JSON with the same envelope. Success or failure is in its status field, not in the HTTP status: check status, then read the result.
Successful endpoint responses return the same top-level metadata. Endpoint-specific data lives in one result key such as organic, images, news, videos, places, or place.
statusnumberrequired
Business status code. 0 means success.
request_idstringrequired
Stable request identifier for support, retries, and log correlation.
elapsed_msnumberrequired
Gateway-observed execution duration in milliseconds.
credits_chargednumber | nullrequired
Actual credits charged after refund logic. null or charge_status: unknown means the charge is not confirmed.
search_typestringoptional
Product-specific response type, when returned by the product.
errorstringrequired
Human-readable failure message.
Request completed successfully. Inspect product-specific outcome fields; no_results alone is not proof of HTTP 404.
Charged
Missing or invalid body or parameters.
Not chargedFix the request first
Missing, invalid, or revoked API key.
Not chargedFix the request first
Resource not found on gateway routing or catalog.
Not chargedFix the request first
Account balance is not enough.
Not chargedFix the request first
QPS or concurrency limit exceeded.
Not chargedSafe to retry
Unexpected internal server error.
Not chargedSafe to retry
Worker returned an upstream fetch or parse error.
Not chargedSafe to retry
No worker session is available.
Not chargedSafe to retry
Gateway timed out waiting for a worker result.
Not chargedSafe to retry
{
"status": 1001,
"error": "unauthorized",
"request_id": "0f3576b2-6e2e-4f1e-bb0e-8cb0d4a60195",
"elapsed_ms": 0,
"credits_charged": 0
}Every product response carries these headers so your client can pace itself and decide whether to retry without parsing the message.
- X-RateLimit-Limit
- Requests per second your account allows.
- X-RateLimit-Remaining
- Requests still allowed in the current second.
- Retry-After
- On a refusal, how many seconds to wait before sending again.
- X-SerpBase-Retryable
- true when resending the same request can succeed; false when the request itself must change.