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

# Errors

> RFC 7807 Problem Details, status code conventions, and how to branch on error codes.

Every error from `api.kash.bot` is an [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) body with `Content-Type: application/problem+json`.

## Wire shape

```json theme={null}
{
  "type": "https://docs.kash.bot/developer-docs/api-errors/INSUFFICIENT_SCOPE",
  "title": "Insufficient scope",
  "status": 403,
  "code": "INSUFFICIENT_SCOPE",
  "detail": "This route requires the 'trades:write' scope. The supplied API key does not include it.",
  "instance": "/v1/trades",
  "requestId": "01HZ…"
}
```

| Field | Use |
| - | - |
| `type` | The URL of the code's page in the [error catalogue](https://docs.kash.bot/developer-docs/api-errors/overview.md). |
| `title` | Short, stable summary. |
| `status` | The HTTP status, repeated in the body. |
| `code` | **The stable, machine-readable identifier. Branch on this.** |
| `detail` | Human-readable explanation of this occurrence. May change; never parse it. |
| `instance` | The request path that failed. |
| `requestId` | Matches the `X-Request-ID` response header. Quote it to support. |

Some codes add extension members at the top level of the body, for example `supported` on `API_VERSION_UNSUPPORTED`. Each code's catalogue page lists them. Retryable errors carry `Retry-After` in seconds.

## How to handle errors

Branch on `code`, not on `status` or the message. A `409` can mean a dozen different things; `code` is unambiguous.

```ts theme={null}
import { KashError } from '@kashdao/sdk';

try {
  await kash.trades.create(body);
} catch (err) {
  if (err instanceof KashError) {
    switch (err.code) {
      case 'INSUFFICIENT_SCOPE':
        // Create a key with trades:write.
        break;
      case 'RATE_LIMIT_EXCEEDED':
        await sleep((err.retryAfterSeconds ?? 1) * 1000);
        break;
      case 'MARKET_NOT_TRADEABLE':
        // Pick another market; this one is resolved, cancelled, inactive or frozen.
        break;
    }
  }
  throw err;
}
```

The SDK also throws typed subclasses (`KashRateLimitError`, `KashAuthorizationError` and so on); see the [catalogue overview](https://docs.kash.bot/developer-docs/api-errors/overview.md#branching-on-errors) for the mapping.

## Status code conventions

| Status | When |
| - | - |
| `200` | Successful read, or a replay of an earlier write. |
| `201` | A resource was created. |
| `202` | Accepted for later work: a high-value trade awaiting confirmation, or a webhook replay. |
| `304` | Conditional request matched; no body. See [ETags](https://docs.kash.bot/developer-docs/rest-api/etags.md). |
| `400` | The request is invalid (`VALIDATION_FAILED`, `OUTCOME_INDEX_INVALID`, `CHAIN_NOT_SUPPORTED`, …). |
| `401` | Authentication failed (`API_KEY_*`, `REQUEST_SIGNATURE_INVALID`). |
| `403` | Authenticated but not allowed (`INSUFFICIENT_SCOPE`, `IP_NOT_ALLOWED`, `ORGANIZATION_INACTIVE`, …). |
| `404` | Not found, or not yours. Ownership-checked routes answer `404` rather than `403`, so ids cannot be probed. |
| `409` | Conflicts with current state (`MARKET_NOT_TRADEABLE`, `SPENDING_LIMIT_EXCEEDED`, `IDEMPOTENCY_KEY_CONFLICT`, …). |
| `410` | `API_VERSION_UNSUPPORTED`. |
| `422` | Well-formed but cannot be processed in the current state (`MARKET_NOT_QUOTABLE`, `MARKET_NOT_DISPUTABLE`). |
| `429` | Too many requests or too many unfinished trades. Honour `Retry-After`. |
| `500` | `INTERNAL_ERROR`. Include the `requestId` when reporting. |
| `503` | Temporarily unavailable (`ROUTE_DISABLED`, `API_TRADE_PROCESSING_HALTED`, `TRADE_ADMISSION_BUSY`, `DEPENDENCY_UNAVAILABLE`, `RATE_LIMIT_UNAVAILABLE`). |
| `504` | `REQUEST_TIMEOUT`. |

## The error catalogue

Every `code` has its own page at `https://docs.kash.bot/developer-docs/api-errors/<CODE>`, which is exactly the `type` URL in the response. The [error catalogue](https://docs.kash.bot/developer-docs/api-errors/overview.md) lists all of them by status.

The `kash` CLI carries an offline copy:

```bash theme={null}
kash explain INSUFFICIENT_SCOPE
```

## What errors never contain

* **No stack traces** and no raw database or chain-node error strings. Details are sanitised.
* **No hints about other users' data.** Reading someone else's trade returns `404 RESOURCE_NOT_FOUND`.
* **No dependency names.** An outage surfaces as a generic `DEPENDENCY_UNAVAILABLE`; your `requestId` lets ZeroID find the cause.

## Reporting problems

Report it from the info button in the Kash web app → **Feedback** → **Report a bug**, with the `requestId`. One id is enough for ZeroID to find the request and everything it triggered.

## Next

> [card] [Idempotency](https://docs.kash.bot/developer-docs/rest-api/idempotency.md)
>
> Retry writes safely without duplicates.

> [card] [Pagination](https://docs.kash.bot/developer-docs/rest-api/pagination.md)
>
> Walk list endpoints with cursors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.