# API errors

> Every error the Ranqo API returns, as problem details with a stable code, what each one means and what to do when you receive it.

Source: https://ranqo.ai/docs/api/errors

An error answers with an HTTP status and a body in the problem details format (`application/problem+json`, RFC 9457). Branch on `code`, which never changes; `title` and `detail` are written for people and can.

```json title="429 Too Many Requests"
{
  "type": "https://ranqo.ai/docs/api/errors#rate_limited",
  "title": "Rate limited",
  "status": 429,
  "detail": "This key is limited to 60 requests a minute.",
  "code": "rate_limited",
  "request_id": "req_7kq2mzd4wax3hrn5tvbfc6jp",
  "retry_after_seconds": 17
}
```

- `type` links to the code's section on this page.
- `detail` says what went wrong and, where there is something to do, what to do.
- `request_id` is also in the `X-Request-Id` header of every response. Quote it when you contact support.
- `errors`, on an invalid parameter, lists each parameter at fault with a message.

| Code | Status | Title |
| --- | --- | --- |
| [`invalid_parameter`](#invalid_parameter) | 400 | Invalid parameter |
| [`unknown_parameter`](#unknown_parameter) | 400 | Unknown parameter |
| [`invalid_cursor`](#invalid_cursor) | 400 | Invalid cursor |
| [`api_key_in_url`](#api_key_in_url) | 400 | API key in URL |
| [`missing_api_key`](#missing_api_key) | 401 | Missing API key |
| [`invalid_api_key`](#invalid_api_key) | 401 | Invalid API key |
| [`api_key_revoked`](#api_key_revoked) | 401 | API key revoked |
| [`api_key_expired`](#api_key_expired) | 401 | API key expired |
| [`api_key_orphaned`](#api_key_orphaned) | 401 | API key no longer valid |
| [`plan_upgrade_required`](#plan_upgrade_required) | 403 | Plan upgrade required |
| [`subscription_inactive`](#subscription_inactive) | 403 | Subscription inactive |
| [`not_found`](#not_found) | 404 | Not found |
| [`route_not_found`](#route_not_found) | 404 | Route not found |
| [`method_not_allowed`](#method_not_allowed) | 405 | Method not allowed |
| [`rate_limited`](#rate_limited) | 429 | Rate limited |
| [`internal_error`](#internal_error) | 500 | Internal error |
| [`service_unavailable`](#service_unavailable) | 503 | Service unavailable |

## Request errors

### `invalid_parameter`

A query parameter has a value the endpoint does not accept: an unknown engine or category, a date that is not a calendar date, a window longer than allowed, a time zone that is not an IANA name, or `period` sent together with `start_date`. The `errors` list names each parameter and why. Fix the value and send the request again.

### `unknown_parameter`

The request sent a query parameter the endpoint does not take. Parameters are checked strictly, so a misspelled one is reported rather than silently ignored. Each reference page lists the parameters its endpoint takes.

### `invalid_cursor`

The `cursor` does not belong to this request: it is malformed, or it was issued for other filters, another endpoint, or a window or board that has moved on since: a prompt's answers over a preset period whose day has turned, or over a window that held no run and now holds one, and Outreach targets after the board was refreshed. Start again from the first page, without a cursor. See [Pagination](https://ranqo.ai/docs/api/pagination).

### `api_key_in_url`

The request address contains an API key. Send the key only in the `Authorization` header. If a real key was sent, revoke it in Settings and create another: an address can end up in logs you do not control.

## Key and plan errors

### `missing_api_key`

The request has no `Authorization` header, or an empty one. Send `Authorization: Bearer` followed by your key.

### `invalid_api_key`

The header does not hold a well-formed Ranqo key, or no key matches it. Check that the whole key was copied. See [Authentication](https://ranqo.ai/docs/api/authentication).

### `api_key_revoked`

The key was revoked in Settings. Create another.

### `api_key_expired`

The key has passed the expiry chosen when it was created. Create another.

### `api_key_orphaned`

The account that owns the key has since joined another team, and keys belong to account owners. Ask the team's owner to create a key in their Settings.

### `plan_upgrade_required`

The account's plan does not include API access. It is included on Pro and above.

### `subscription_inactive`

The account's trial or subscription has ended. Choose a plan to use the API again.

## Missing things

### `not_found`

The brand, run, prompt, audit or recommendation does not exist, or this key cannot read it: it belongs to another account, the brand was removed, or the key is restricted to other brands. The API answers all of these alike, so it never tells a caller whether something it cannot read exists.

### `route_not_found`

There is no endpoint at this path. Check the path against the reference; every path starts with `/v1`.

### `method_not_allowed`

The API is read-only: every endpoint answers `GET` only.

## Limits and outages

### `rate_limited`

The key has used its requests for this minute, or has failed authentication too often. Wait the seconds in the `Retry-After` header, or in `retry_after_seconds`, then retry. See [Rate limits](https://ranqo.ai/docs/api/rate-limits).

### `internal_error`

Something failed on Ranqo's side. Retry after a short wait; if it keeps happening, contact support with the `request_id`.

### `service_unavailable`

A service the API depends on is briefly unavailable, and the API refuses the request rather than serve it without counting it. Retry after the seconds in the `Retry-After` header.