Errors
Every error the program, the API, the relay and the SDK raise, with its code, its cause and what to do.
An error comes from one of three places. The program refuses a transaction with a numbered custom error. The API and the relay answer with one JSON envelope and a stable code. The SDK throws a TalariaError carrying either an API code or a code of its own.
Program errors#
Anchor numbers a program's custom errors from 6000 in declaration order. A failed transaction's logs end with Program 5hJVoxABR1b9QqnQ7FfZDtY2fgNGkUsQtPBqjyBLPTU3 failed: custom program error: 0x…, the code in hexadecimal. Errors below 6000 are Anchor's own account checks (for example 2006, a seeds mismatch) and run before the handler; Instructions gives the order.
| Code | Hex | Name | Message |
|---|---|---|---|
| 6000 | 0x1770 | Unauthorized | The signer is not authorized for this operation. |
| 6001 | 0x1771 | InvalidConfiguration | Configuration values are invalid. |
| 6002 | 0x1772 | InsolventConfiguration | The remaining message fee does not cover the relay fee. |
| 6003 | 0x1773 | DayLengthLocked | Changing day length after a pass purchase is forbidden. |
| 6004 | 0x1774 | InvalidInboxKey | The inbox key must not be all zero bytes. |
| 6005 | 0x1775 | InboxKeyUnchanged | The new inbox key must differ from the old key. |
| 6006 | 0x1776 | ArithmeticOverflow | The arithmetic result does not fit its integer type. |
| 6007 | 0x1777 | InvalidFieldElement | The scalar is outside the BN254 field. |
| 6008 | 0x1778 | InvalidTier | The pass tier is not configured. |
| 6009 | 0x1779 | InvalidPassLength | The pass length is not configured. |
| 6010 | 0x177a | PoolFull | The Merkle pool is full. |
| 6011 | 0x177b | WrongDay | The post is for a different day. |
| 6012 | 0x177c | UnknownRoot | The root is not in the accepted root history. |
| 6013 | 0x177d | InvalidPayload | The encrypted payload is malformed. |
| 6014 | 0x177e | SpentNullifier | The nullifier is already spent. |
| 6015 | 0x177f | ProofInvalid | The proof could not be verified. |
| 6016 | 0x1780 | VaultInsufficientFunds | The vault cannot pay the relay fee while preserving its rent reserve. |
| 6017 | 0x1781 | DayNotClosable | The day is not old enough for closing nullifiers. |
| 6018 | 0x1782 | InvalidCloseAccounts | The nullifier and relay account pair is invalid. |
| 6019 | 0x1783 | InvalidClock | The chain clock is invalid. |
Unauthorized#
- Raised by
initializewhen the signer is not the program's upgrade authority orprogram_datais not the program's ProgramData account, and byset_configwhen the signer is notConfig.admin. Sign with the upgrade authority or the admin.
InvalidConfiguration#
- Raised by
initializeandset_configwhen a fee is zero, the share is above 10,000 bps, the day length is zero, the root history size is outside 1 to 64, a tier or length is zero, or the tiers or lengths are not strictly increasing. Correct theConfigArgs; the checks are listed in order.
InsolventConfiguration#
- Raised by
initializeandset_configwhenmessage_fee × (10,000 − protocol_share_bps) / 10,000is belowrelay_fee, so a pass could not pay for the messages it sends. Lower the relay fee or the share, or raise the message fee.
DayLengthLocked#
- Declared and raised by no instruction in this build.
set_configaccepts a new day length.
InvalidInboxKey#
- Raised by
open_inboxandrotate_inbox_keywhen the key is 32 zero bytes. Send the X25519 public key derived on Cryptography.
InboxKeyUnchanged#
- Raised by
rotate_inbox_keywhen the new key equals the current one. Derive the key for the next version.
ArithmeticOverflow#
- Raised when a checked sum or product leaves its type: the largest pass price in
ConfigArgs,key_version + 1inrotate_inbox_key, the expiry day or price inbuy_pass,day + 1or a relay's balance inclose_nullifiers. Correct the input; with valid configuration and real days it does not occur.
InvalidFieldElement#
- Raised by
buy_passwhenid_commitmentis not below the BN254 field modulus, or when a Poseidon hash of the leaf or the tree fails. SendPoseidon(secret)as a 32-byte big-endian scalar.
InvalidTier#
- Raised by
buy_passwhentieris not 0, 1 or 2. The API maps it toINVALID_TIER.
InvalidPassLength#
- Raised by
buy_passwhendaysis not one ofConfig.lengths. The API maps it toINVALID_PASS_LENGTH. Read the lengths fromGET /pool.
PoolFull#
- Raised by
buy_passwhen the pool already holds 2^26 leaves. No pass can be added to this pool.
WrongDay#
- Raised by
postwhendayis not today on the chain clock. A proof made just before a day boundary lands after it. The API maps it toWRONG_DAY; prove again for the new day.
UnknownRoot#
- Raised by
postwhenrootis not among the latestroot_history_sizeroots. New passes moved the root on. The API maps it toUNKNOWN_ROOT; fetch the pool leaves and prove again.
InvalidPayload#
- Raised by
postwhen the payload is shorter than 251 bytes or its first byte is not 1. The API maps it toINVALID_PAYLOAD. The layout is on Log entry format.
SpentNullifier#
- Raised by
postwhen the Nullifier account exists. That counter was already used today, by this message or another. The API maps it toSPENT_NULLIFIER. Look for the nullifier in the Log: if its entry carries the same payload hash, the message landed.
ProofInvalid#
- Raised by
postwhen the Groth16 proof does not verify against the root, day, nullifier, payload hash and relay. A changed payload or a proof made for another relay fails here. The API maps it toPROOF_INVALID.
VaultInsufficientFunds#
- Raised by
postwhen payingrelay_feewould take the Vault below its rent-exempt minimum. The API maps it toVAULT_EMPTY, retryable: the post spends nothing, and it lands once pass purchases have refilled the Vault.
DayNotClosable#
- Raised by
close_nullifierswhenday + 1 < todaydoes not hold. Close a day two or more days old.
InvalidCloseAccounts#
- Raised by
close_nullifierswhen the remaining accounts are empty or odd in number, or a pair is not writable, not owned by the program, of another day, paired with a relay other than the one recorded, or at an address other than its PDA. Pass each Nullifier followed by its recordedrelay, both writable.
InvalidClock#
- Raised by
buy_pass,postandclose_nullifierswhen the chain clock's unix timestamp is negative.
API errors#
The API and the relay answer every failure with this envelope, whatever the HTTP status:
{
"error": {
"code": "UNKNOWN_ROOT",
"message": "The root is not in the accepted root history.",
"retryable": true,
"stage": "simulation",
"programError": {
"programId": "5hJVoxABR1b9QqnQ7FfZDtY2fgNGkUsQtPBqjyBLPTU3",
"name": "UnknownRoot",
"number": 6012
}
}
}
- codestring
- One of the codes below. Branch on this.
Required
- messagestring
- A sentence that can be shown as it is.
Required
- retryableboolean
- Whether sending the same request again can succeed.
Required
- stagestring
- The step that failed:
validation,auth,read,upload,build,wallet,co_sign,simulation,sendorconfirmation.Required
- fieldErrorsRecord<string, string[]>
- Messages per request field, with
VALIDATION_ERROR. - programErrorobject
programId,nameandnumberof the program that refused the transaction.- retryAfterSecondsinteger
- Seconds to wait, with
RATE_LIMITED. - requestIdstring
- The request's id, with
INTERNAL_ERROR.
A program refusal during a build, a submission or a relay's simulation is mapped by its error name: UnknownRoot, WrongDay, ProofInvalid, InvalidPayload, InvalidTier, InvalidPassLength, VaultInsufficientFunds and SpentNullifier take the codes below, with stage simulation and retryable true only for UNKNOWN_ROOT, WRONG_DAY and VAULT_EMPTY. A refusal because an account already exists (the System Program's "already in use") is INBOX_ALREADY_OPEN at the API, since open_inbox is the only built transaction that creates one, and SPENT_NULLIFIER at a relay. A refusal for lack of lamports (the System Program's "insufficient lamports") is INSUFFICIENT_FUNDS. Any other refusal is CHAIN_REFUSED. The message is the program's own.
The status, stage and retryable columns are what the code sends. Where a code is raised in more than one place with different values, the row says so.
| Code | HTTP | Stage | Retryable | Meaning |
|---|---|---|---|---|
VALIDATION_ERROR | 400 | validation | no | A body, path or query value failed its schema, or the JSON is invalid. fieldErrors names each field. |
UNAUTHORIZED | 401 | auth | no | Not raised: the API has no sign-in. |
ORIGIN_NOT_ALLOWED | 403 | validation | no | The request's Origin is not on the allowlist. |
NOT_FOUND | 404 | read | no | No route at this path. |
PROGRAM_UNAVAILABLE | 409 | read | yes | The API found no Config or Pool account: Talaria is not initialized on this cluster. GET /pool, GET /pool/leaves, GET /relays and GET /stats answer it; GET /health answers status: "waiting" instead. Ask again once initialize has landed. |
CONFIGURATION_REQUIRED | 409 | build | no | Not raised by the API or relay in this build. The SDK throws it, see SDK errors. |
IDEMPOTENCY_CONFLICT | 409 | send | no | POST /transactions/submit for a build already submitted under another idempotencyKey. The same key answers with the first submission's status. The fixture API raises it for a key reused with a different body. |
TRANSACTION_EXPIRED | 409 | confirmation | yes | The relay's transaction passed its last valid block height without landing. Post again; the nullifier is unspent. |
PAYLOAD_TOO_LARGE | 413 | validation | no | The request body is over the server's limit (16,384 bytes at a relay), or a relay received a payload over 3,408 bytes. Split the text into more parts. |
UNSUPPORTED_MEDIA_TYPE | 415 | validation | no | A POST body that is not application/json. |
SIMULATION_FAILED | 422 | simulation | no | Not raised in this build; failed simulations answer with a mapped code or CHAIN_REFUSED. |
CHAIN_REFUSED | 422 | simulation | as sent | A program refused the transaction with an error not mapped above, or the API could not build or take a transaction: a build over the packet size, or signed bytes that differ from the build or are not a transaction (not retryable). |
RATE_LIMITED | 429 | read | yes | The fixture API only, at its session limit. |
INTERNAL_ERROR | 500 | read | yes | An unexpected server failure; requestId identifies it. The client also uses it for a non-JSON answer below HTTP 500. |
UPSTREAM_UNAVAILABLE | 502 | read | yes | Set by the client when an answer of HTTP 500 or above is not an envelope. |
INBOX_NOT_FOUND | 404 | read | no | Not raised by the API, which serves the whole inbox directory. The SDK throws it. |
INBOX_ALREADY_OPEN | 409 | simulation | no | POST /tx/open-inbox for a wallet whose Inbox account exists. Rotate the key with POST /tx/rotate-inbox-key instead. |
NAME_NOT_FOUND | 404 | read | no | Not raised by the API: .sol names resolve on the device. The SDK throws it. |
LOG_ENTRY_NOT_FOUND | 404 | read | no | The fixture API only: no entry for this signature. |
LOG_ENTRY_NOT_INDEXED | 404 | read | yes | GET /log/entries/:signature has no post for this signature yet. Ask again; the SDK waits on it after a relay answers. |
LOG_SEGMENT_NOT_FOUND | 404 | read | no | GET /log/segments/:n or GET /inboxes/segments/:n beyond the last sealed segment. Read the rest from GET /log/head or GET /inboxes/head. |
TRANSACTION_NOT_FOUND | 404 | read | yes | POST /transactions/submit or GET /transactions/:id with a build id the API did not make or has forgotten. Build the transaction again. The fixture API raises it, not retryable, for an unknown build id on submit and on GET /transactions/:id. |
NO_PASS | 409 | build | no | A fixture relay scenario. The SDK throws it before proving. |
DAILY_LIMIT_REACHED | 409 | build | no | A fixture relay scenario. The SDK throws it before proving. |
PASS_EXPIRED | 409 | build | no | A fixture relay scenario. The SDK throws it before proving. |
UNKNOWN_ROOT | 409 | simulation | yes | From UnknownRoot. Fetch the pool leaves and prove again. |
SPENT_NULLIFIER | 409 | simulation | no | From SpentNullifier. Check the Log for the nullifier before sending anything new. |
WRONG_DAY | 409 | simulation | yes | From WrongDay. Prove again for today. |
PROOF_INVALID | 422 | simulation | no | From ProofInvalid. |
RELAY_MISMATCH | 422 | simulation | yes | The proof's relay input is not this relay's address. Prove again for this relay, or post to the relay named. |
RELAY_UNAVAILABLE | 503 | send | yes | A relay whose key cannot pay for the transaction: its simulation fails without logs. Also a fixture relay scenario. The SDK moves on to the next relay, and throws it when no relay is left to try. |
INDEXER_UNAVAILABLE | 503 | read | yes | A fixture API scenario. |
INVALID_PAYLOAD | 422 | validation | no | At a relay: the payload does not hash to publicInputs.payloadHash. From InvalidPayload (stage simulation): a payload shorter than 251 bytes or not version 1. |
INVALID_TIER | 400 | read | no | POST /tx/buy-pass with a tier id other than light, daily or frequent; from InvalidTier with stage simulation. |
INVALID_PASS_LENGTH | 400 | simulation | no | From InvalidPassLength: a length not in GET /pool's lengths. |
INSUFFICIENT_FUNDS | 422 | build, simulation | no | A payer short of SOL. At the API: a wallet holding under 10,000 lamports when any /tx build is asked for (stage build), or one that cannot pay a pass's price or an Inbox's rent (stage simulation). At a relay: its key cannot front the Nullifier's rent. Fund the payer and send again. |
VAULT_EMPTY | 503 | simulation | yes | From VaultInsufficientFunds: the Vault cannot pay the relay fee and keep its rent reserve. Post again later; nothing was spent. |
A transaction the wallet signed can still fail after submission. GET /transactions/:id then answers status: "failed" or "expired" with an error object: stage (build, wallet-rejected, wallet-changed, simulation, send or confirm), message, retryable, an optional nextStep, and program (address, code, name) when a program refused it.
SDK errors#
The SDK throws TalariaError, an Error with code, message, retryable and, from a relay, relayUrl. An error from the API arrives as ApiClientError with the envelope in body and its code in code. Progress callbacks report either as { stage: 'failed', error } with the same fields.
import { TalariaError, type Talaria } from '@talaria/sdk'
export async function sendOnce(talaria: Talaria, to: string, text: string) {
try {
return await talaria.send(to, text)
} catch (error) {
if (error instanceof TalariaError && error.code === 'DAILY_LIMIT_REACHED') return null
throw error
}
}
Codes of the SDK's own#
| Code | Retryable | Thrown when |
|---|---|---|
WALLET_REJECTED | no | The wallet refused or failed to sign the key derivation message in unlock, or a transaction in openInbox, rotateInboxKey or buyPass. |
KEYS_LOCKED | Declared; not thrown in this build. | |
NO_PASS | no | send: no pass in the pool derives from this wallet's pass seed. |
DAILY_LIMIT_REACHED | no | send: every unexpired pass has used, or reserved for a pending part, each counter of today. |
PASS_EXPIRED | no | send: every pass this wallet holds has expiryDay before today. |
COUNTERPARTY_NO_INBOX | no | send to a wallet or .sol name whose wallet has no Inbox, and room creation with such a member. |
INVALID_PRIVATE_LINK | Declared; not thrown in this build. A link that does not parse throws a plain Error. | |
DECRYPTION_FAILED | Declared; not thrown in this build. An entry that does not open is skipped by scan. | |
WRITER_VERIFICATION_FAILED | Declared; not thrown in this build. An entry whose writer key or MAC does not check is skipped by scan. | |
PROVING_FAILED | no | Reported for any failure that is neither a TalariaError nor an API error, such as the prover rejecting its input. |
RELAY_UNAVAILABLE | yes | send: no relay URL is configured and GET /relays lists none. When every relay was tried, the last relay's own error is thrown. |
INDEXER_UNREACHABLE | yes | scan: the Log could not be downloaded. |
API codes the SDK throws itself#
| Code | Retryable | Thrown when |
|---|---|---|
VALIDATION_ERROR | no | buyPass with a tier id or length GET /pool does not list; send to a room this device has not joined; a room member that is not a wallet. |
NOT_FOUND | no | acceptRoom, addRoomMember or removeRoomMember with a room id this device does not hold. |
INBOX_NOT_FOUND | no | rotateInboxKey before the wallet has an Inbox in the inbox directory. |
NAME_NOT_FOUND | no | send, createRoom or addRoomMember with a .sol name that lookup does not find: not a valid name, or no owner in the client's nameService. |
CONFIGURATION_REQUIRED | no | prove, send or demoProof without prover artifacts; demoProof without a verification key; lookup of a .sol name with nameService: 'sns' and no rpcUrl. |
CHAIN_REFUSED | as reported | A wallet-signed transaction ended failed. |
TRANSACTION_EXPIRED | as reported | A wallet-signed transaction ended expired. Build and sign it again. |
UNKNOWN_ROOT | yes | send: the tree rebuilt from GET /pool/leaves does not match GET /pool's root. Retry. |
SPENT_NULLIFIER | no | send: the nullifier of a pending part is in the Log with a different payload hash. |
Each send part starts at the next relay in the list, in turn. A relay's error with retryable true, or a network failure, moves send on to the next relay with the same payload and nullifier. Before it does, the SDK looks for the nullifier in the Log, so a post that landed behind a lost response is reported as landed and never sent twice.
A part left pending from a finished day is looked up in the Log by its old day and nullifier when send or retry reaches it again. If it landed, it counts as sent. If not, the SDK drops the old attempt and posts the part again today with a new proof, so a pending part never ends in WRONG_DAY.