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

# Errors

> Error codes integrators encounter and how to handle them.

Every error thrown or returned by the SDK has a typed `code` and a human-readable `message`. Switch on `code`; show `message` only as a debug aid (don't display verbatim to end users).

```ts theme={null}
try {
  // ...
} catch (err) {
  if (err.code === "INTENT_DEADLINE_PAST") { /* ... */ }
}
```

## Validation errors

Returned by `intent.build()` and `intent.submit()` when input is malformed.

| Code                   | Meaning                                                          | What to do                                           |
| ---------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
| `INTENT_DEADLINE_PAST` | `deadline` is in the past                                        | Recompute deadline                                   |
| `UNSUPPORTED_CHAIN`    | `sourceChain` or `destChain` not supported                       | Check [supported chains](/concepts/supported-chains) |
| `UNSUPPORTED_ASSET`    | `tokenIn` or `tokenOut` not supported on the given chain         | Use a supported asset                                |
| `AMOUNT_BELOW_MINIMUM` | `amountIn` below the per-asset minimum                           | Increase the amount                                  |
| `AMOUNT_ABOVE_MAXIMUM` | `amountIn` above the per-asset maximum                           | Reduce the amount or split into multiple intents     |
| `INVALID_RECIPIENT`    | `recipient` is malformed                                         | Validate address format                              |
| `MIN_OUTPUT_INVALID`   | `minAmountOut` is zero, negative, or exceeds `amountIn` notional | Set a sensible slippage floor                        |
| `METADATA_TOO_LARGE`   | `metadata` exceeds the size limit                                | Trim metadata                                        |

## Liquidity errors

Returned by `intent.submit()` and surfaced in `failed` status events.

| Code                      | Meaning                                               | What to do                                         |
| ------------------------- | ----------------------------------------------------- | -------------------------------------------------- |
| `NO_SOLVER_AVAILABLE`     | No solver took the intent before deadline             | Retry with longer deadline or wider `minAmountOut` |
| `MIN_OUTPUT_UNATTAINABLE` | Solvers can't deliver `minAmountOut` at current rates | Lower `minAmountOut` (accept more slippage)        |

## Rate limiting

| Code                        | Meaning                                                             | What to do                                                                    |
| --------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `RATE_LIMITED` (HTTP 429)   | Platform intent throughput ceiling hit                              | Back off exponentially with jitter; see [rate limits](/reference/rate-limits) |
| `WEBHOOK_SIGNATURE_INVALID` | HMAC verification failed on a webhook delivery (when webhooks ship) | Check your `secret`; reject the request                                       |

There is no API key, so no auth errors. Signature-protected endpoints (recipient flows, settle) reject per-request signatures with `400` and a specific message.

## Network errors

| Code                      | Meaning                                                       | What to do                                                                                                                         |
| ------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `RPC_UNREACHABLE`         | Source-chain RPC failed during validation                     | Retry with backoff                                                                                                                 |
| `TACHYON_API_UNREACHABLE` | The relayer at `https://relayer.tachyon.pe` is not responding | Retry with backoff; real-time status is surfaced in the user dashboard at [testnet.app.tachyon.pe](https://testnet.app.tachyon.pe) |
| `REQUEST_TIMEOUT`         | Request exceeded the SDK's internal timeout                   | Retry; consider raising `requestTimeoutMs` in SDK options                                                                          |

## Settlement errors

Surfaced in `failed` status events. **None of these result in lost funds**, the user is automatically refunded via the on-chain escape mechanism.

| Code                  | Meaning                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------- |
| `SETTLEMENT_REVERTED` | Destination tx reverted; refund initiated                                                   |
| `EXECUTION_TIMEOUT`   | Solver did not complete settlement within the protocol's execution window; refund initiated |
| `INTENT_EXPIRED`      | Deadline passed before any solver took the intent; refund initiated                         |

## Recipient / sweep errors

| Code                   | Meaning                                                  | What to do                                                                       |
| ---------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `VIEWING_KEY_MISSING`  | No viewing key loaded in the SDK session                 | Register the recipient via `POST /recipient/register` and import the viewing key |
| `SAFE_NOT_DEPLOYED`    | The Safe at the stealth address hasn't been deployed yet | Deploy via [`POST /recipient/deploy-safe`](/api/relayer) first                   |
| `RELAY_PROXY_REVERTED` | The Safe's `execTransaction` reverted on-chain           | Inspect the target call; funds remain safe at the stealth Safe                   |

## Handling pattern

```ts theme={null}
async function safeSubmit(intent: SignedIntent) {
  let attempt = 0;
  while (attempt < 3) {
    try {
      return await tachyon.intent.submit(intent);
    } catch (err) {
      if (err.code === "RATE_LIMITED" || err.code === "TACHYON_API_UNREACHABLE") {
        await delay(2 ** attempt * 500);
        attempt++;
        continue;
      }
      throw err; // validation/liquidity errors don't benefit from retry
    }
  }
  throw new Error("submit failed after retries");
}
```

<Card title="Rate limits" icon="gauge" href="/reference/rate-limits">
  Platform throughput limits.
</Card>