Errors, limits & headers
Errors use HTTP status codes and one JSON shape:
{
"error": {
"status": 429,
"code": "rate_limited",
"message": "Rate limit exceeded (60 requests/minute for your plan)."
},
"search_metadata": {
"id": "srch_…",
"status": "error",
"api_version": "v1"
}
}| Status | code | Meaning | Charged? |
|---|---|---|---|
| 400 | bad_request | A parameter is missing or invalid. The message names it. | No |
| 401 | unauthorized | Missing, invalid or revoked key, or the account is disabled. | No |
| 402 | out_of_credits | No searches left this period (Free plan, or a paid plan without an active subscription). | No |
| 429 | rate_limited | Too many requests this minute. Wait Retry-After seconds. | No |
| 502 | providers_failed | Every upstream provider failed or timed out. Safe to retry. | No — refunded |
| 500 | internal_error | Something broke on our side. | No |
Rate limits
Each plan has a per-minute limit per API key (see pricing), plus a per-IP limit that stops abuse. Limits use fixed one-minute windows.
Response headers
| Header | Meaning |
|---|---|
| X-RateLimit-Limit | Requests allowed per minute on your key. |
| X-RateLimit-Remaining | Requests left in this minute. |
| X-RateLimit-Reset | Seconds until the window resets. |
| Retry-After | On 429: seconds to wait. |
| X-Quota-Remaining | Searches left this period, including bonus credits ("unlimited" on unlimited plans). |
| X-Cache | HIT (free, from cache) or MISS. |
| X-Request-Id | Same as search_metadata.id — quote it when you contact support. |
Retrying
Retry 429 after Retry-After, and 502/500 with exponential backoff (1s, 2s, 4s…). Don't retry 400, 401 or 402 without changing something.