Skip to content
API Reference

Search is only available in production builds. Try building and previewing the site to test it out locally.

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"
}
FieldTypeDescription
okbooleanAlways false on an error.
codestringStable, machine-readable error code. Branch on this.
messagestringHuman-readable explanation. Do not parse it; it can change.

HTTP status codes

StatusMeaning
200 OKThe request succeeded.
400 Bad RequestA parameter is missing or invalid, or the chain is not supported by this endpoint.
401 UnauthorizedNo valid credentials, or a second factor is required. Inspect code.
403 ForbiddenThe credentials are valid but not allowed to perform this action.
404 Not FoundThe resource does not exist or does not belong to your account.
409 ConflictThe resource is in a state that prevents the action. Usually safe to retry later.
422 Unprocessable EntityThe request is well formed but cannot be executed, or an upstream service refused it.
429 Too Many RequestsYou went over a rate limit. Back off and retry.
500 Internal Server ErrorSomething went wrong on Proxima’s side.
503 Service UnavailableA 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.

CodeCauseWhat to do
missing_authorizationNo Authorization header on a protected endpoint.Send Authorization: Bearer <jwt>.
invalid_tokenThe JWT is malformed, expired, signed by another environment or does not match its session.Sign in again.
invalid_sessionThe session was revoked or has expired.Sign in again. Other devices may have revoked it.
license_requiredA base token was used outside the account endpoints.Upgrade the token onto a license with POST /auth/upgrade.
invalid_licenseThe license in the token is inactive or no longer exists.Pick another license and upgrade again.
license_not_ownedThe license in the token was reassigned to another account.Upgrade onto a license you own.
2fa_requiredThe 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

CodeStatusDescription
bad_request400A parameter is missing, malformed or out of range. message names it.
unsupported_chain400The endpoint does not serve this chain. The body adds chain.
unauthorized401The action was refused for this caller, for example a wrong or reused second factor.
forbidden403The caller is authenticated but lacks the right, for example on a shared launch or an admin route.
not_found404The resource does not exist or is not visible to the caller.
conflict409The resource changed or is in the wrong state, for example a stale If-Match.
unprocessable422The request is valid but cannot be executed as asked.
too_many_requests429A 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.

CodeStatusExtra fieldsMeaning and recovery
launch_migrating409noneThe bonding curve sold out and the pool it graduates into is not seeded yet. Retry in a few seconds.
venue_ungated422noneNo recorded pool exists for this launch yet, so an engine or guard cannot be armed safely. message names the missing fact.
upstream_failure422serviceA third-party service (an RPC, a launchpad API, an exchange) refused the request. message is prefixed with the service name.
partial_failure422native_withdrawn, blockedPart 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_pending409request_id, tx_hashesThe request was sent but not confirmed yet. Do not send it again. Check the transactions, then retry only if they failed.
lane_unavailable503maybe_takenThe 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_unavailable503noneAn automation engine could not be reached, so nothing was armed. Safe to retry.
service_unavailable503noneA dependency is briefly unavailable. Safe to retry.
internal_error500noneAn 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

SituationRetry?
429, service_unavailable, pace_unavailable, launch_migratingYes, with exponential backoff.
lane_unavailable with maybe_taken: falseYes.
lane_unavailable with maybe_taken: true, lane_pendingOnly after checking the transactions.
partial_failureOnly for the part that did not land, without the blocked wallets.
2fa_requiredYes, once, with the challenge answer and the identical body.
Other 4xxNo. Fix the request first.
500Once, unless message is a documented refusal. Report it if it repeats.