The API uses standard HTTP status codes to indicate success or failure.
| Status | Description |
|---|---|
| 400 | Invalid request parameters |
| 401 | Missing or invalid API key |
| 403 | Access not allowed for current plan |
| 404 | Resource not found |
| 429 | Rate limit exceeded, or Discovery fair-use cap reached |
| 500 | Internal server error |
| 503 | Temporary service unavailability |
Errors are returned as JSON.
Examples of possible error responses:
{
"field": "platform",
"message": "Invalid platform value"
}{
"detail": "Authentication credentials were not provided."
}{
"error": "Too many requests. Please try again later.",
"retry_after": 42
}The response also includes a Retry-After header with the same value (seconds to wait).
A 429 can mean two different things. Both use an error field, so tell them apart by whether the response includes retry_after:
| Cause | How to recognize it | Clears when |
|---|---|---|
| Per-minute rate limit | Has a retry_after field and a Retry-After header | After the wait window — safe to retry with backoff |
| Fair-use cap reached | No retry_after; message mentions the credit limit | On subscription renewal — retrying does not help |
{
"error": "Discovery API credit limit reached. Credits reset on subscription renewal."
}See Usage & limits for how the cap works.
- Always inspect the HTTP status code first.
- Do not retry 4xx errors unless the request is modified.
- Retry transient errors (rate-limit
429, 5xx) using exponential backoff. - Do not retry the Discovery fair-use cap
429— it clears only on subscription renewal.