# Errors

> Every BestSERP error code with its HTTP status, what causes it and whether credits are charged, plus the error format and the requestId to quote.

Source: https://bestserp.com/docs/errors (updated 2026-11-14)

Errors share one format. Quote the `requestId` (also in the `X-Request-Id` header) when you contact support.

**402 Payment Required**

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "This request needs 2 credit(s); your balance is 1. Top up in the dashboard."
  },
  "requestId": "5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"
}
```

## Status codes

| HTTP | error.code | When | Credits |
| --- | --- | --- | --- |
| 202 | `-` | Not finished within timeout (or async: true). Poll pollUrl. | Reserved |
| 400 | `invalid_request` | Malformed body or a parameter out of range. | No |
| 400 | `unknown_parameter` | A field the API does not know (typo?). | No |
| 400 | `unsupported_parameter` | A known field that this endpoint does not support yet (e.g. location). | No |
| 401 | `missing_api_key / invalid_api_key` | No key, or the key is wrong or revoked. | No |
| 402 | `insufficient_credits` | Your balance is too low for this request. | No |
| 403 | `account_suspended` | The account is suspended. | No |
| 404 | `not_found` | Unknown requestId, or it belongs to another account. | - |
| 429 | `rate_limited` | Too many requests this minute. See Retry-After. | No |
| 502 | `search_failed` | The search could not be completed (blocked or timed out). | Refunded |
| 503 | `busy` | No capacity right now. Retry after Retry-After seconds. | Refunded |

Retry `429` and `503` after `Retry-After`; retry `502` once or twice. Fix `400`, `401` and `402` in your request or account instead of retrying. See [rate limits](https://bestserp.com/docs/rate-limits) and [credits](https://bestserp.com/docs/credits).
