Errors

Wallet-Facing Errors

How your wallet should answer Phoenix. See Errors on the wallet operations page for how each answer is read.

Launch Refusals

A launch token Phoenix refuses is answered by the embed's boot configuration call with a body of { "error", "message", "details" }, one code per reason (malformed_token, invalid_signature, unknown_key, token_expired, environment_not_active, unsupported_currency and the rest). The full list, with each code's HTTP status and details, is under Refusals You Can Read. The embed also reports the code to your page as an error event (see Parent Bridge).

Player-Facing Phoenix Reasons

When a player command is rejected, the command reply carries a structured reason:

{
  "kind": "command",
  "outcome": "rejected",
  "reason": {
    "code": "validation",
    "message": "insufficient funds",
    "details": { "reason": "insufficient_funds" }
  }
}

reason.code is a closed set. Branch on it in client code; never parse reason.message, which is a human-readable string for display and logs. A reason can also carry details, and on internal reasons retriable (true when trying again may work) and sometimes retry_after_ms.

Every refused bet names what happened in reason.details.reason: the order's own reason (for example insufficient_funds, wallet_declined, wallet_not_called, expired, market_closed, market_paused, insufficient_position), or the one Phoenix refused it with before it reached the market (for example below_min_order_size, above_max_order_size, player_banned, operator_not_active). The coarse reason.code puts several of these under validation, so word a refusal from details.reason, never from code alone: a wallet that declined a bet is not the player's order being invalid. The embed does this for you (see Player Protection).

When your wallet declines a reservation with any code other than insufficient_funds, the reply also names your code:

{
  "kind": "command",
  "outcome": "rejected",
  "reason": {
    "code": "validation",
    "message": "your wallet declined this bet",
    "details": { "reason": "wallet_declined", "wallet_code": "limit_exceeded" }
  }
}

The embed shows the player what your code means, which you set under Player protection in the back office; Phoenix gives limit_exceeded, self_excluded, cooling_off, verification_required, account_blocked and player_not_found a meaning already (see Declining a Reservation).

When Phoenix did not send the reservation to your wallet at all, because one of its own rules refused it (for example wallet_url_not_public), the reply says so and names Phoenix's code instead:

{
  "kind": "command",
  "outcome": "rejected",
  "reason": {
    "code": "internal",
    "message": "this bet could not be sent to your wallet; nothing was taken",
    "details": { "reason": "wallet_not_called", "phoenix_code": "wallet_url_not_public" }
  }
}

A bet sent without an idempotency key is refused with idempotency_required. One more code is reserved but not sent today: unknown_mutation. A command the embed's connection does not know is answered unknown_request, and a player-only command from a visitor login_required.

The reason.message strings, by code:

A retry under the same idempotency key with identical parameters is safely de-duplicated: it returns the original order with no error. Only a key reused with different parameters conflicts. A resend of a bet Phoenix already took is answered with that bet's first outcome, even if the market has closed since.

When Phoenix cannot tell whether a bet was taken (it could not confirm that it stored the order), it answers with an error reply unconfirmed, not a refused command: the bet may exist. Send the same bet again under the same idempotency key, and do not mint a new key, which would be a second bet. The reply to the resend says what happened, and Phoenix takes the bet once either way.

A buy reply waits up to 5 seconds for the order's outcome. If your wallet has not answered by then, the reply is accepted, and a later refusal shows on the order itself (below).

Show friendly copy to players. Keep reason.code and reason.message in logs for support.

Rejected After Acceptance

An order can be rejected after Phoenix accepted it, for example when your wallet answers after the reply. The player then sees the order end as rejected, and your support team reads why on the order in the back office (Trades and the player's page). The stored reason is one of:

When the book refuses an order your wallet had funded, the reservation is released with a release_cash (reason ORDER_REJECTED). When your wallet declined the reservation, nothing was held and nothing is released.

Operator API Errors

See Operator API errors.