# Errors

> How the Proxima API reports failures, the error codes it returns and how to recover from each.

The API uses conventional HTTP status codes. `2xx` means the request succeeded, `4xx` means the request cannot
succeed as sent, and `5xx` means Proxima could not complete it.

## Error object

Every error raised by an endpoint returns a JSON body with the same three fields. Some codes add context fields,
listed below. A few errors raised before the endpoint runs, such as a malformed JSON body, come back as plain text
instead; see [Known behaviors](/getting-started/known-behaviors/#errors-that-are-not-json).

```json
{
  "ok": false,
  "code": "unauthorized",
  "message": "unauthorized"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `ok` | boolean | Always `false` on an error. |
| `code` | string | Stable, machine-readable error code. Branch on this. |
| `message` | string | Human-readable explanation. Do not parse it; it can change. |

> **Info:** A few older endpoints answer `ok: false` with a `message` but no `code`. Check `ok` first, then fall back to the
> HTTP status when `code` is missing.

## HTTP status codes

| Status | Meaning |
| --- | --- |
| `200 OK` | The request succeeded. |
| `400 Bad Request` | A parameter is missing or invalid, or the chain is not supported by this endpoint. |
| `401 Unauthorized` | No valid credentials, or a second factor is required. Inspect `code`. |
| `403 Forbidden` | The credentials are valid but not allowed to perform this action. |
| `404 Not Found` | The resource does not exist or does not belong to your account. |
| `409 Conflict` | The resource is in a state that prevents the action. Usually safe to retry later. |
| `422 Unprocessable Entity` | The request is well formed but cannot be executed, or an upstream service refused it. |
| `429 Too Many Requests` | You went over a rate limit. Back off and retry. |
| `500 Internal Server Error` | Something went wrong on Proxima's side. |
| `503 Service Unavailable` | A dependency is unavailable. Read `code` before retrying a money operation. |

## Authentication errors

These are returned with `401` by the authentication layer, before the endpoint runs. Their `message` is always
the generic `unauthorized`, so rely on `code`.

| Code | Cause | What to do |
| --- | --- | --- |
| `missing_authorization` | No `Authorization` header on a protected endpoint. | Send `Authorization: Bearer <jwt>`. |
| `invalid_token` | The JWT is malformed, expired, signed by another environment or does not match its session. | Sign in again. |
| `invalid_session` | The session was revoked or has expired. | Sign in again. Other devices may have revoked it. |
| `license_required` | A base token was used outside the account endpoints. | Upgrade the token onto a license with `POST /auth/upgrade`. |
| `invalid_license` | The license in the token is inactive or no longer exists. | Pick another license and upgrade again. |
| `license_not_owned` | The license in the token was reassigned to another account. | Upgrade onto a license you own. |
| `2fa_required` | The action is protected by a second factor. | Answer the challenge and retry. See [Two-factor step-up](/getting-started/two-factor-step-up/). |

A `403` with `code: "read_only_token"` means the token is read-only and the request was not a `GET`.

> **Warning:** The web client signs the user out when it receives `invalid_session` or `invalid_token`. Do the same: retrying
> with the same token cannot succeed.

Some license-scoped endpoints answer `{ "ok": false, "message": "Invalid license key" }` when the license attached
to the request is no longer valid. Treat it like `invalid_license`.

## Request errors

| Code | Status | Description |
| --- | --- | --- |
| `bad_request` | 400 | A parameter is missing, malformed or out of range. `message` names it. |
| `unsupported_chain` | 400 | The endpoint does not serve this chain. The body adds `chain`. |
| `unauthorized` | 401 | The action was refused for this caller, for example a wrong or reused second factor. |
| `forbidden` | 403 | The caller is authenticated but lacks the right, for example on a shared launch or an admin route. |
| `not_found` | 404 | The resource does not exist or is not visible to the caller. |
| `conflict` | 409 | The resource changed or is in the wrong state, for example a stale `If-Match`. |
| `unprocessable` | 422 | The request is valid but cannot be executed as asked. |
| `too_many_requests` | 429 | A rate limit was hit. No `Retry-After` header is sent. |

## Execution errors

Endpoints that send transactions can fail after part of the work has happened. These codes tell you what state
you are in, which matters more than the status code.

| Code | Status | Extra fields | Meaning and recovery |
| --- | --- | --- | --- |
| `launch_migrating` | 409 | none | The bonding curve sold out and the pool it graduates into is not seeded yet. Retry in a few seconds. |
| `venue_ungated` | 422 | none | No recorded pool exists for this launch yet, so an engine or guard cannot be armed safely. `message` names the missing fact. |
| `upstream_failure` | 422 | `service` | A third-party service (an RPC, a launchpad API, an exchange) refused the request. `message` is prefixed with the service name. |
| `partial_failure` | 422 | `native_withdrawn`, `blocked` | Part of a multi-wallet operation landed and is already booked; the rest did not. `blocked` lists wallets that cannot send at all. Exclude them before retrying. |
| `lane_pending` | 409 | `request_id`, `tx_hashes` | The request was sent but not confirmed yet. **Do not send it again.** Check the transactions, then retry only if they failed. |
| `lane_unavailable` | 503 | `maybe_taken` | The execution engine did not complete the request. If `maybe_taken` is `false`, nothing was sent and you can retry. If it is `true`, the request may still execute: check before retrying. |
| `pace_unavailable` | 503 | none | An automation engine could not be reached, so nothing was armed. Safe to retry. |
| `service_unavailable` | 503 | none | A dependency is briefly unavailable. Safe to retry. |
| `internal_error` | 500 | none | An unexpected error. Retry once; contact support if it persists. |

```json
{
  "ok": false,
  "code": "lane_pending",
  "message": "sent, not confirmed: do not send it again",
  "request_id": "b7c1e0a4-6f0e-4a4e-9d6e-2a3f0c9b1d55",
  "tx_hashes": ["5h3xQ…", "2Lk9p…"]
}
```

> **Danger:** Never retry a money operation blindly. Retrying after `lane_pending`, or after `lane_unavailable` with
> `maybe_taken: true`, can send the same buy, sell or transfer twice.

## Retry strategy

| Situation | Retry? |
| --- | --- |
| `429`, `service_unavailable`, `pace_unavailable`, `launch_migrating` | Yes, with exponential backoff. |
| `lane_unavailable` with `maybe_taken: false` | Yes. |
| `lane_unavailable` with `maybe_taken: true`, `lane_pending` | Only after checking the transactions. |
| `partial_failure` | Only for the part that did not land, without the `blocked` wallets. |
| `2fa_required` | Yes, once, with the challenge answer and the identical body. |
| Other `4xx` | No. Fix the request first. |
| `500` | Once, unless `message` is a documented [refusal](/getting-started/known-behaviors/#refusals-sent-as-500). Report it if it repeats. |
