- API Reference
- Getting Started
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.
{ "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. |
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. |
A 403 with code: "read_only_token" means the token is read-only and the request was not a GET.
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. |
{ "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…"]}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. Report it if it repeats. |