Arkena Docs

Errors come from two places: the wallet provider (thrown as Error instances with a numeric code) and the Arkena backend (HTTP errors with a JSON body). This page lists both.

Provider errors

Every failure path from provider.request(...) rejects with an Error whose code is one of the values below.

Code

try {
  await provider.request({ method: "canton_connect" });
} catch (err) {
  if (err && typeof err === "object" && "code" in err) {
    switch ((err as { code: number }).code) {
      case 4001: /* user rejected */ break;
      case 4100: /* unauthorized — wallet locked or no permission */ break;
      case -32003: /* transaction rejected by wallet policy */ break;
      case -32601: /* method not found / not allowed */ break;
    }
  }
}

EIP-1193 / CIP-103 codes

Code	Name	When
`4001`	`USER_REJECTED`	The user clicked Reject in the popup.
`4100`	`UNAUTHORIZED`	The wallet is locked, or the origin has no permission for this action.
`4200`	`UNSUPPORTED`	The request is well-formed but not supported by this wallet version.
`4900`	`DISCONNECTED`	The wallet is not connected to a Canton network.

JSON-RPC standard codes

Code	Name	When
`-32601`	`METHOD_NOT_FOUND`	The method name is not in the wallet's allowlist.
`-32602`	`INVALID_PARAMS`	The params shape doesn't match what the method expects.
`-32603`	`INTERNAL_ERROR`	Unhandled error in the wallet. Treat as transient.
`-32003`	`TX_REJECTED`	The wallet's policy checks rejected the transaction (e.g., signing a hash that doesn't match the displayed summary).

Recovery guidance

4001 — surface a passive Try again button. Don't auto-retry; the user said no.
4100 — most often the wallet is locked. The wallet itself shows an unlock UI on the next interactive request; your dApp doesn't need to act.
4200 — the user has an older wallet build. Show "please update Arkena."
4900 — the wallet has no active Canton connection. Show a connectivity warning; recovers on its own when the network returns.
-32601 — your dApp called a method that isn't in this wallet's allowlist. Check the canonical method names in Provider methods.
-32602 — wrong params shape. Check the method's documentation.
-32003 — the user (or the wallet's policy) rejected the transaction. Re-prepare and re-prompt; the same hash will not pass again.

Backend errors

Backend HTTP errors return a uniform JSON body:

Code

{
  "error": "INSUFFICIENT_BALANCE",
  "message": "Wallet balance 5.0 CC is below the required 100.0 CC.",
  "details": { "available": "5.0", "required": "100.0" }
}

HTTP	`error` examples	When
`400`	`INVALID_REQUEST`, `MISSING_FIELD`	Validation failed. The body's `details` field tells you which field.
`401`	`MISSING_TOKEN`, `EXPIRED_TOKEN`	SIWC JWT missing or expired. Re-run SIWC.
`403`	`WRONG_PARTY`	JWT belongs to a different party than the request claims.
`404`	`NOT_FOUND`	The referenced resource (NFT, listing, intent) does not exist.
`409`	`INSUFFICIENT_BALANCE`, `LISTING_GONE`, `RACE_LOST`	A conflict at execute time. Refetch state and retry from prepare.
`429`	`RATE_LIMITED`	Too many requests from this origin. Back off per the `Retry-After` header.
`503`	`SETTLEMENT_TIMEOUT`, `LEDGER_UNAVAILABLE`	Transient. Retry the same execute call (idempotent on `commandId`).

Recovery guidance

401 / 403 — auth failure. Re-do SIWC and retry. If it persists, the wallet's connected party doesn't match the JWT's party.
409 RACE_LOST — someone else took the listing first. Refetch the page state; the listing is gone.
409 INSUFFICIENT_BALANCE — show the user the gap.
429 — back off per the Retry-After header.
503 — safe to retry the same execute payload. The endpoint dedupes on commandId.

What's next

Provider methods — full method reference, with the errors each can raise.
Sign and submit transactions — the procedure-side view of these errors, with copyable handlers.