> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rhinestone.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Common Orchestrator errors and how to resolve them

Every non-2xx response shares the same shape:

```json theme={null}
{
  "code": "INSUFFICIENT_LIQUIDITY",
  "message": "...",
  "traceId": "...",
  "details": { /* optional, code-specific */ }
}
```

Switch on `code`, not `message`. The full code/HTTP table lives in the [versioning guide](./api-versioning#error-codes).

```ts theme={null}
switch (err.code) {
  case "INSUFFICIENT_LIQUIDITY":
    // err.details: { availableIntents, unfillable }
    break;
  case "VALIDATION_ERROR":
    // err.details: [{ message, context? }]
    break;
  case "TOO_MANY_REQUESTS":
    // honour the Retry-After header
    break;
  default:
    // unknown codes — fall through to a generic error
    break;
}
```

The list is extensible — always include a default fallback for codes you don't recognise.

<AccordionGroup>
  <Accordion title="INSUFFICIENT_LIQUIDITY (422)">
    The account balance can't cover the requested tokens together with gas and fees, or the cost to claim funds (e.g. on Ethereum mainnet) is too high to fill profitably.

    `details` contains `availableIntents` (alternative routes you could fall back to) and `unfillable` (the routes that couldn't be filled and why).

    Make sure the account is deployed and funded. For SDK users, the [spendable amount utility](/smart-wallet/chain-abstraction/source-token-amount) gives an estimate of how much can be spent.
  </Accordion>

  <Accordion title="VALIDATION_ERROR (400)">
    The request payload didn't validate. Common causes:

    * Unsupported `destinationChainId` — check the [supported chains](/home/resources/supported-chains).
    * Unsupported token address on the destination chain.
    * Mainnet chain ids on a development API key, or testnet chain ids on a production key.
    * Malformed CAIP-2 chain ids — they must be `eip155:<chainId>` strings.
    * Missing or unknown `x-api-version` header.

    `details` is an array of `{ message, context? }` entries.
  </Accordion>

  <Accordion title="UNAUTHORIZED (401)">
    The API key is missing or invalid. Pass it in `x-api-key`. [Reach out to us](https://t.me/konradkopp) if you need a key.

    Make sure you're using a development API key for testnets and a production API key for mainnets.
  </Accordion>

  <Accordion title="NOT_FOUND (404) on submit">
    `POST /intents` returns 404 when the `intentId` no longer exists server-side — typically because the quote TTL elapsed or the quote store was restarted.

    Re-quote and re-sign. Don't retry the submit with the same `intentId`.
  </Accordion>

  <Accordion title="UNPROCESSABLE_CONTENT (422) on submit">
    The signature didn't validate against the account. Either the typed data was modified before signing, or the signer isn't an authorised owner of the account.

    Forward `signData.origin[]` and `signData.destination` verbatim to `signTypedData` — don't reconstruct the types client-side. For smart accounts, make sure the validator wraps the signature using its expected encoding.
  </Accordion>

  <Accordion title="TOO_MANY_REQUESTS (429)">
    Rate limited. Honour the `Retry-After` header before retrying.
  </Accordion>
</AccordionGroup>