# Errors (/docs/api/errors)



All errors are returned as JSON with an `error` message and the appropriate HTTP status.

```json
{ "error": "Insufficient credits" }
```

Status codes [#status-codes]

| Status | Meaning                                                                            |
| ------ | ---------------------------------------------------------------------------------- |
| `400`  | Invalid request. Bad role, malformed URL, URL too long, or missing required field. |
| `401`  | Missing, invalid, or revoked API key.                                              |
| `402`  | Insufficient credits. Top up in the dashboard.                                     |
| `404`  | Resource not found, or belongs to a different team.                                |
| `409`  | A matching search is already in progress. Poll the existing `searchId`.            |
| `429`  | Rate limit exceeded. Honor the `Retry-After` header.                               |
| `500`  | Unexpected server error. Safe to retry after a short delay.                        |

Retry guidance [#retry-guidance]

* `429` and `5xx`: safe to retry with backoff.
* `400`, `401`, `402`, `404`: the request itself is wrong. Do not retry.
* `409`: you have an in-flight search. Poll its status instead of retrying `find-email`.

Common mistakes [#common-mistakes]

* **Forgetting the `Content-Type: application/json` header**: returns `400 Invalid JSON body`.
* **Using a revoked key**: returns `401 Invalid or revoked API key`. Create a new key in the dashboard.
* **Submitting a role outside the allowlist**: returns `400` with the list of valid roles. Use exact casing.