> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reposeek.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API errors

> HTTP statuses and error codes returned by the Reposeek API.

# API errors

Expected API errors return JSON with an `error.code` and `error.message`.
They also include an `X-Request-Id` header for support and debug correlation.

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Invalid search request"
  }
}
```

Use `error.code` for application logic. Messages may change.

## Error codes

| HTTP status | Code                    | Meaning                                                                                                     | Fix                                                      |
| ----------- | ----------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `401`       | `missing_api_key`       | Missing or malformed `Authorization: Bearer <api-key>` header.                                              | Set `REPOSEEK_API_KEY` or send the Bearer header.        |
| `401`       | `invalid_api_key`       | Key is unknown, revoked, inactive, or the account cannot use it.                                            | Create or regenerate a key in the dashboard.             |
| `422`       | `validation_error`      | Request JSON or search body is invalid.                                                                     | Check `query`, `limit`, JSON syntax, and unknown fields. |
| `429`       | `rate_limit_exceeded`   | Too many requests in the current rate window.                                                               | Retry later or reduce request rate.                      |
| `429`       | `quota_exceeded`        | Search quota is exhausted for the current quota window. The payload includes usage metadata when available. | Wait for reset, upgrade, or manage billing.              |
| `503`       | `embedding_unavailable` | Embedding provider is temporarily unavailable.                                                              | Retry later.                                             |
| `503`       | `reranker_unavailable`  | Reranking provider is temporarily unavailable.                                                              | Retry later.                                             |

Quota errors may include:

```json theme={null}
{
  "error": {
    "code": "quota_exceeded",
    "message": "You've used your 10 free searches for this month. Upgrade to Pro for 100 searches/month. Same search quality, higher monthly volume.",
    "usage": {
      "remaining_searches": 0,
      "next_reset_at": "2026-06-01T12:00:00+00:00"
    }
  }
}
```

Unexpected server errors may return a simpler server-error body. Treat any 5xx as retryable with backoff unless your application has stronger context.