Errors

Every error returns a code and a human readable message in a consistent envelope. This page lists every code swqos.com can return, what causes it, and what to do about it.

The shape#

Every failure, on both HTTPS and QUIC, uses the same envelope. Branch on code, which is stable, and show message to a human. Do not parse the message.

error

1{
2  "error": {
3    "code": "INSUFFICIENT_BALANCE",
4    "message": "insufficient prepaid balance"
5  }
6}

Every code#

HTTP	Code	Cause	Fix
400	`INVALID_BASE64`	The transaction field is not valid base64.	Base64-encode the serialized transaction, not the JSON or a hex string.
400	`INVALID_TRANSACTION`	The serialized envelope is malformed or out of bounds.	Send a fully signed legacy or versioned transaction under 1232 bytes.
400	`INVALID_REQUEST`	A request field is missing or malformed.	Check the JSON body shape against the reference.
401	`UNAUTHORIZED`	No Bearer credential was supplied.	Send an Authorization header of the form 'Bearer <key>'.
401	`INVALID_API_KEY`	The key could not be decoded.	Check the key is intact and begins with usq_live_. Keys are secrets, so never log them.
402	`INSUFFICIENT_BALANCE`	The account has no prepaid credit left.	Deposit SOL from the dashboard. Credit appears once the deposit finalizes.
403	`ACCOUNT_DISABLED`	The account exists but is switched off.	Contact support. This is usually a billing or abuse review.
409	`SUBMISSION_IN_PROGRESS`	The same signature is already in flight.	Wait for the first submission to return rather than retrying immediately.
503	`BILLING_UNAVAILABLE`	Billing persistence is unhealthy.	Retry with backoff. Nothing was charged.
503	`AUDIT_UNAVAILABLE`	Audit persistence is unhealthy.	Retry with backoff. Nothing was charged.
503	`UPSTREAM_UNAVAILABLE`	We could not forward the transaction.	Retry. Any charge for this submission is reversed automatically.

Register outcomes#

Your transaction register records an outcome for every submission, including ones that never reached the network. These are the values you will see.

Outcome	Meaning
`accepted`	Charged and acknowledged upstream.
`duplicate`	Already accepted within 90s. Not charged.
`in_progress`	An identical submission is still active.
`invalid_transaction`	The envelope failed validation. Not charged.
`rejected`	Blocked by account or billing policy. Not charged.
`forward_failed`	Upstream did not accept it. The charge was reversed.

accepted means we forwarded your bytes and the upstream acknowledged the stream. It is not proof the transaction landed on chain. See billing for why that distinction is load bearing.

Which errors cost money#

Almost none of them. The full boundary is in billing, but in short:

Free: every 400, every 401, 402, 403 and 409. If we refuse a submission, you do not pay for it.
Charged then reversed: 503 UPSTREAM_UNAVAILABLE. The charge is written before we forward, so when forwarding fails we write a matching refund. It nets to zero.
Charged: only a successful submission. And it stays charged even if the transaction never lands, because forwarding is the thing you bought.

For retry guidance on each class of failure, see limits and behaviour.