Errors

path/query/body failed binding or validation, or a business rule about one input (a field named in errors)

What to do: Fix the inputs details.errors lists: each field is the name you sent (dotted when nested), and every failing input is reported at once.

details: errors: [{ field, message, reason? }]; with some, max / min (decimal strings for money)

a referenced resource does not exist

What to do: details.field names the reference that doesn't exist: check that id.

details: field

POST /webhooks/verify: the signature doesn't match, or is older than 5 minutes; a send route: the transaction isn't the payer's signature over what the intent prepared (Payments and transactions § Sending a signed transaction)

something only test mode does asked in live mode (a test bill, a faucet, a test payment)

a transfer whose paying wallet is the wallet it pays (a payment, a subscription, a refund, a release)

missing / invalid JWT or API key, an ended login

What to do: Check the key: a missing, unknown, deleted or expired key answers this.

authenticated but not allowed (role, peer resource)

What to do: The key can't do this: the route needs an admin key, the On-Behalf-Of value isn't a member this key may act for, or a key wrote a members.* policy (policies change in the dashboard).

a member doing what their organization's policy doesn't allow them, reads of what the policy governs included

What to do: A member's key, while the organization's policy details.policy is off for members: the organization turns it on in its settings. details.field names the input it refuses (a checkout's successUrl or cancelUrl, members.checkoutRedirects): send it without. Organization keys never get it.

details: policy; field when the policy governs a request field (members.checkoutRedirects, on by default: a member's successUrl / cancelUrl, routes/checkout-sessions.md)

a member's checkout whose fees.processingFee differs from their organization's checkout.customerPaysProcessingFee (Checkout sessions § Fees)

details: field (fees.processingFee)

unknown or out-of-scope resource; also any route hidden by a guard

What to do: Check the id and the key's mode (test or live): a resource of another space answers the same, so existence is never revealed.

the path exists, not with this method; the Allow header lists its methods. Answered before any credential is read, like the 404 of a path no route has

a unique value already exists (e.g. a duplicate reference or email)

What to do: details.field names the value already used in this space (the value itself is never echoed): pick another one.

details: field (never the value)

a state conflict no more specific code covers

a transaction sent already: running, or completed (Payments and transactions § Sending a signed transaction)

removing a member (DELETE /members/:userUuid, DELETE /team/:userUuid for an admin who kept a personal space), or closing an organization, while the organization holds a member's live funds: release them first (Members and held funds); deleting the organization's live wallet of a chain (DELETE /wallets/:uuid) while it holds members' live funds in that chain's currencies, which their release is paid from (Wallets)

details: DELETE /wallets/:uuid: heldEntries (an integer: the held lines on that chain not settled yet)

trusting a member (POST /members/:userUuid/trust) whose own wallets accept none of the organization's currencies: trusted, nobody could pay them (their checkouts would all answer merchant_not_ready), and trust can't be undone. Trust them once they've added one (Members and held funds)

opening a checkout nobody could pay: the space's wallets (the organization's, while it holds the member's funds) accept no currency, or no token for a subscription; a subscription for a member whose funds the organization holds (fundsHeld: one-time payments only until trusted) (Checkout sessions); at a payer's intent (POST /hosted/payments/intent, POST /hosted/subscriptions/intent), a member's checkout whose organization takes a fee on it and has no wallet on the paid currency's chain anymore (organizationFeeNoWallet: a guard, the fee never dropped from a new payment; removing the organization's wallet of a chain already removes that chain's currencies from its members, so an open checkout meets currency_not_accepted first; a subscription signed before keeps billing without the fee, Members and held funds)

details: reason: noWallet, organizationNoWallet, noTokenWallet, fundsHeld, organizationFeeNoWallet

the Idempotency-Key's first request is still running (idempotency): retry once it answered

What to do: Retry once the first request has answered, with the same key.

a checkout of a removed member's or a closed organization's space: it takes no payment (Checkout sessions)

an Idempotent route's body over 1 MiB (idempotency)

the Idempotency-Key was used for another request (idempotency): send a new key

What to do: Send a new key: one key names one operation.

rate limit hit (see below)

What to do: Wait details.retryAfterSeconds (also sent as the Retry-After header), then send the same request again, with the same Idempotency-Key: the refused one did nothing.

details: limit, periodSeconds, retryAfterSeconds; limitedBy (and what it counts) on a route with several limits

server error

What to do: Retry a read or an idempotent create; quote requestId when asking support.

inviting someone already in the organization with that role and mode (Invitations)

cancelling a subscription, raising its allowance or its maximum, once it is stopped (it ends with its paid period; customer-side routes), a merchant's POST /subscriptions/:uuid/cancel?immediate=false of a stopped one, or a merchant's POST /subscriptions/:uuid/cancel or /test-bill of a cancelled one

the request ran past the server's deadline: retry (idempotent reads) or check the resource before retrying a write

What to do: Retry a read; check the resource before retrying a write.

The payer sent what QBitFlow didn't prepare, or too late (§ Sending a signed transaction). tx_expired also ends an EVM token payment whose network fee fell too far since its intent, and a Solana transaction whose blockhash expired before it landed: create the intent again

The payer sent what QBitFlow didn't prepare, or too late (§ Sending a signed transaction). tx_expired also ends an EVM token payment whose network fee fell too far since its intent, and a Solana transaction whose blockhash expired before it landed: create the intent again

The payer the wallet replaced the transaction with another one (a cancel, other values): it never ran (a speed-up with the same values is followed)

The payer signed something already used: prepare the transaction again

The payer asked for what the subscription's state refuses

The payer asked for what the subscription's state refuses

The payer asked for what the subscription's state refuses

The payer asked for what the subscription's state refuses

The payer asked for what the subscription's state refuses

The payer sent a token payment or a subscription (both sent and paid for by QBitFlow's operator) while another one from the same wallet in the same token is still confirming, or failed under 2 minutes ago: retry in a couple of minutes. Every casing of an EVM address is the same wallet

The payer doesn't hold enough of the token (or SOL, for a native payment): top up

The payer can't pay the network fee (ETH, SOL…): top up the network's coin

The payer granted QBitFlow less than this amount: increase the allowance

The payer granted an allowance that expired: approve again

The payer hasn't approved Permit2 for the token (EVM): approve it, then retry

The payer signed too long ago: sign again (a free trial's message: ask a new intent)

The payer a bill above the subscription's maximum per period (the price moved): approve a higher maximum

The payer asked for an amount outside the subscription's limits (allowance_too_low, Solana only: a top-up of fewer periods than were spent since the last one granted, which its program refuses until its upgrade; details.minPeriods, the fewest periods it takes)

The payer asked for an amount outside the subscription's limits (allowance_too_low, Solana only: a top-up of fewer periods than were spent since the last one granted, which its program refuses until its upgrade; details.minPeriods, the fewest periods it takes)

The payer asked for an amount outside the subscription's limits (allowance_too_low, Solana only: a top-up of fewer periods than were spent since the last one granted, which its program refuses until its upgrade; details.minPeriods, the fewest periods it takes)

The payer asked for an amount outside the subscription's limits (allowance_too_low, Solana only: a top-up of fewer periods than were spent since the last one granted, which its program refuses until its upgrade; details.minPeriods, the fewest periods it takes)

The payer uses a token the network doesn't support

The payer can't act: the transaction failed for a reason no decoder recognized

The payer can't act: QBitFlow's side (reported, fixed by QBitFlow)

The payer can't act: QBitFlow can't send on the network for now, or has no fresh USD price for the currency (missing, older than 5 minutes, or a stablecoin off its peg by more than 5 %), retry later