SDK
Errors
The GeodeError every SDK method rejects with, its codes, which codes each method raises, and how other failures are mapped.
Every method of a Geode client rejects with a GeodeError. Branch on code; message is a sentence an interface can show.
import { GeodeError } from '@geode/sdk'
try {
await geode.store(file)
} catch (error) {
if (!(error instanceof GeodeError)) throw error
switch (error.code) {
case 'INSUFFICIENT_BALANCE':
console.log('Shield more SOL.')
break
case 'WALLET_REJECTED':
console.log('The wallet declined.')
break
case 'IRYS_UNAVAILABLE':
console.log('Retry with the same file.')
break
default:
console.log(error.message)
}
}GeodeError
class GeodeError extends Error {
readonly code: GeodeErrorCode
constructor(code: GeodeErrorCode, message: string, options?: ErrorOptions)
}name'GeodeError'GeodeError.codeGeodeErrorCodemessagestringmessage.causeunknownApiClientError (with status and the full error envelope), the wallet's exception, the prover's exception, or the validation error.GeodeErrorCode
GeodeErrorCode is every relayer API code plus three codes that only happen on the holder's device. The API codes, their HTTP statuses and their meaning are listed at /docs/api#errors. The SDK raises several API codes itself, on the device, under the conditions in Codes by method.
Device codes
| Code | Happens when |
|---|---|
WALLET_REJECTED | The client has no wallet, the wallet declines or fails the key message, returns a signature that is not 64 bytes, has neither signTransaction nor signAndSendTransaction for shield, or throws while signing the shield transaction |
WRONG_KEY | A key is malformed or does not decrypt a ciphertext, or the ciphertext is not a Geode sealed file |
PROOF_FAILED | No proving artifacts URL is set, geode.wasm or geode_final.zkey cannot be downloaded, the prover throws, or its public signals differ from the payment |
Codes by method
Codes the SDK raises from its own code paths. • is a check in the method's own steps; unlock is the first vault call of the client, when the wallet signs the key message and the manifest and notes are read. open (key) is open called with a key, which never unlocks. store reads the manifest again after each upload, so the manifest's read codes are its own. /upload marks a relayer code that reaches the method only from that request.
| Code | store | open (key) | open | share | list | balance | shield | unshield | recover |
|---|---|---|---|---|---|---|---|---|---|
WALLET_REJECTED | unlock | unlock | unlock | unlock | unlock | • | unlock | • | |
WRONG_KEY | • | • | • | unlock | unlock | unlock | unlock | unlock | • |
PROOF_FAILED | • | • | • | ||||||
VALIDATION_ERROR | • | • | • | unlock | unlock | • | • | • | • |
CONFIGURATION_REQUIRED | • | • | • | unlock | unlock | unlock | unlock | • | • |
NOT_FOUND | • | • | • | • | unlock | unlock | unlock | unlock | • |
IRYS_UNAVAILABLE | • | • | • | unlock | unlock | unlock | unlock | unlock | • |
PAYLOAD_TOO_LARGE | • | • | • | unlock | unlock | unlock | unlock | unlock | • |
IDEMPOTENCY_CONFLICT | • | ||||||||
INSUFFICIENT_BALANCE | • | • | |||||||
QUOTE_FAILED | • | • | |||||||
RELAYER_FAILED | • | • | • | unlock | unlock | • | • | • | • |
UNKNOWN_ROOT | • | unlock | unlock | unlock | • | • | • | • | |
UPSTREAM_UNAVAILABLE | • | • | • | • | • | • | • | • | • |
STORAGE_PAYEE_KEY_REQUIRED | /upload |
Each method's page says the condition behind each code.
Codes from the relayer
Every request a method makes can also reject with the code the relayer returns, unchanged. A method's requests:
| Method | Relayer requests |
|---|---|
store | GET /quote, GET /config, GET /tree, POST /pay, POST /upload for the file; GET /manifest and GET /tree to read the manifest again; GET /quote, GET /tree, POST /pay, POST /upload for the manifest; plus unlock |
open with a key | GET /config |
open, share, list | On unlock: GET /manifest, GET /tree, GET /config |
balance | GET /tree, plus unlock |
shield | GET /config, GET /tree, POST /shield/build, POST /shield/confirm, plus unlock |
unshield | GET /unshield/quote, GET /tree, GET /config, POST /unshield, plus unlock |
recover | GET /manifest, GET /tree, GET /config |
The ciphertext itself comes from the gateway, whose 404 is NOT_FOUND and whose other failures are IRYS_UNAVAILABLE. See API overview and /docs/api#errors.
How other failures are mapped
Every method passes its failure through one mapping before it rejects:
| Failure | Becomes |
|---|---|
A GeodeError | Itself |
A relayer error envelope (ApiClientError) | A GeodeError with the envelope's code and message, the ApiClientError as cause |
| A relayer error reply that is not the error envelope | UPSTREAM_UNAVAILABLE for an HTTP status of 500 or more, else INTERNAL_ERROR |
| A relayer success reply that is not JSON | RELAYER_FAILED |
| An invalid argument | VALIDATION_ERROR with the validation message |
| A relayer reply that does not match the contract | RELAYER_FAILED |
Anything else: a network failure, a thrown TypeError or RangeError | UPSTREAM_UNAVAILABLE with the original message, the original as cause |
The retry rules for store are on store.