Rate limits and errors
Requests per key, the daily limit on live Google calls, caching, and every error code the API returns.
Rate limits
| Limit | Value | When it's reached |
|---|---|---|
| Requests per key | 120 a minute | 429 rate_limited with a Retry-After header in seconds |
| Live Google calls per organization | 2,000 a day (resets at midnight UTC) | 429 rate_limited with a Retry-After header counting down to midnight UTC |
Responses to requests with a valid key also carry standard RateLimit headers for the per-key limit.
The daily Google limit protects the organization owner's Google quota. It only counts requests that have to ask Google:
- Search performance requests that SEObolt can't answer from its stored data (see Search performance). A request can use more than one call, for example when it also fetches the comparison period.
- Every GA4 analytics request that isn't already cached.
Requests answered from stored or cached data keep working after the daily limit is reached, and rank tracking requests never count toward it.
Caching
Live Google results are cached for 6 hours per organization, site and set of parameters. A repeat request in that time is answered from the cache, shows "cached": true and doesn't use a Google call.
If Google fails and an older copy of the same request is in the cache, you get that copy with "stale": true instead of an error.
Error format
Every error has the same shape:
{ "error": { "code": "not_found", "message": "Site not found." } }
Use code in your code; message is for people and can change.
Error codes
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | A parameter is invalid. The message says which, for example "dimension must be one of: date, query, page." |
| 401 | unauthorized | The key is missing, in the wrong format, unknown or revoked |
| 403 | tier_required | The organization's plan doesn't include API access |
| 404 | not_found | Unknown endpoint, or a site or keyword the key can't read |
| 405 | method_not_allowed | The request used a method other than GET or HEAD |
| 409 | google_not_connected | The organization owner hasn't connected Google, or the connection has expired. The owner needs to reconnect Google. |
| 409 | ga4_not_linked | No GA4 property is linked to the site. Link one in Settings β API access. |
| 409 | organization_unavailable | The organization has no owner |
| 429 | rate_limited | A rate limit was reached. Wait for the Retry-After seconds. |
| 500 | internal_error | Something went wrong in SEObolt. Try again. |
| 502 | upstream_unavailable | Google didn't return data and there was no cached copy. Try again shortly. |
A site that belongs to another organization, or that your key isn't allowed to read, returns 404, never 403.
Last updated 2026-10-28