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.

TypeScript
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

TypeScript
class GeodeError extends Error {
  readonly code: GeodeErrorCode
  constructor(code: GeodeErrorCode, message: string, options?: ErrorOptions)
}
GeodeError
name
'GeodeError'
Always GeodeError.
code
GeodeErrorCode
The stable code.
message
string
A sentence saying what failed. For a relayer error it is the relayer's message.
cause
unknown
The original failure when there is one: the relayer's ApiClientError (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

CodeHappens when
WALLET_REJECTEDThe 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_KEYA key is malformed or does not decrypt a ciphertext, or the ciphertext is not a Geode sealed file
PROOF_FAILEDNo 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.

Codestoreopen (key)opensharelistbalanceshieldunshieldrecover
WALLET_REJECTEDunlockunlockunlockunlockunlock•unlock•
WRONG_KEY•••unlockunlockunlockunlockunlock•
PROOF_FAILED•••
VALIDATION_ERROR•••unlockunlock••••
CONFIGURATION_REQUIRED•••unlockunlockunlockunlock••
NOT_FOUND••••unlockunlockunlockunlock•
IRYS_UNAVAILABLE•••unlockunlockunlockunlockunlock•
PAYLOAD_TOO_LARGE•••unlockunlockunlockunlockunlock•
IDEMPOTENCY_CONFLICT•
INSUFFICIENT_BALANCE••
QUOTE_FAILED••
RELAYER_FAILED•••unlockunlock••••
UNKNOWN_ROOT•unlockunlockunlock••••
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:

MethodRelayer requests
storeGET /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 keyGET /config
open, share, listOn unlock: GET /manifest, GET /tree, GET /config
balanceGET /tree, plus unlock
shieldGET /config, GET /tree, POST /shield/build, POST /shield/confirm, plus unlock
unshieldGET /unshield/quote, GET /tree, GET /config, POST /unshield, plus unlock
recoverGET /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:

FailureBecomes
A GeodeErrorItself
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 envelopeUPSTREAM_UNAVAILABLE for an HTTP status of 500 or more, else INTERNAL_ERROR
A relayer success reply that is not JSONRELAYER_FAILED
An invalid argumentVALIDATION_ERROR with the validation message
A relayer reply that does not match the contractRELAYER_FAILED
Anything else: a network failure, a thrown TypeError or RangeErrorUPSTREAM_UNAVAILABLE with the original message, the original as cause

The retry rules for store are on store.