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

# Errors

> Every error answers a fixed code, a message and the request id.

Every error response has this body:

```json theme={null}
{
  "error": "The request is not valid. See details.",
  "code": "invalid_request",
  "requestId": "bd6dfdcb-2d50-46b2-af72-786c15b1cf82",
  "details": [{ "path": "body.metric", "issue": "Invalid option: expected one of \"share_price\"|\"tvl\"" }]
}
```

* `code` is fixed and machine-readable. Branch on `code`; the `error` message text may change.
* `requestId` is the same value as the `x-request-id` response header. Quote it when you contact Kamui.
* `details` appears on invalid requests and on some transaction errors. It lists up to 10 `{ path, issue }` entries; `path` names the failing field, such as `body.address`, or the failing transaction, such as `transactions.1`.

## Error codes

### Every action

| HTTP | `code` | Meaning | What to do |
| - | - | - | - |
| 400 | `invalid_request` | A field is missing, has the wrong type or value, is unknown, or is named twice in one object (`is a duplicate field`). | Fix the field named in `details`. |
| 401 | `unauthorized` | The API key is missing, malformed, unknown, revoked or expired. | Check the `x-partner-api-key` header. Ask Kamui if the key was rotated or revoked. |
| 404 | `route_not_found` | The action does not exist. | Check the action name. |
| 404 | `vault_not_found` | No vault has this slug. | Use a slug from [Data conventions](/api/data-conventions). |
| 405 | `method_not_allowed` | The method is not `POST`. | Use `POST`. |
| 409 | `vault_not_active` | The vault exists but is not open yet. | Try again after the vault opens. |
| 413 | `payload_too_large` | The body is over 16 KiB. | Send a smaller body. |
| 415 | `unsupported_media_type` | The body was not sent as JSON. | Send `Content-Type: application/json`. |
| 429 | `rate_limited` | Your client is over its per-minute limit for this group of actions (read or transaction actions). See [Limits](/api/overview#limits). | Wait the `Retry-After` header's seconds before the next request. |
| 500 | `internal_error` | Unexpected error. | Retry later. If it persists, contact Kamui with the request id. |
| 502 | `upstream_error` | A data source (the vault indexer or the chain) returned an error. | Retry with exponential backoff. |
| 503 | `service_unavailable` | The service is temporarily unavailable. The transaction actions also answer it when the API cannot check your rate limit for a moment. | Retry with exponential backoff. |
| 504 | `upstream_timeout` | A data source did not answer in time. | Retry with exponential backoff. |

### `users.transactions`

| HTTP | `code` | Meaning | What to do |
| - | - | - | - |
| 400 | `invalid_cursor` | The cursor was changed or does not decode, or it comes from a page with another `address`, `slug` or `types`. | Start again from the first page. |
| 503 | `history_unavailable` | The history could not be read: a data source failed or timed out, or the wallet has more than 1,000 request, cancel and claim rows, or more than 1,000 rows at one timestamp. No partial page is returned. | Retry with exponential backoff. If it persists for one wallet, contact Kamui. |

### `transaction.quote` and `transaction.build`

See [Build transactions](/api/transactions) for the order in which a build runs its checks. "Build only" errors are reported by a quote in `availability.reason` instead, or not checked by it.

| HTTP | `code` | Meaning | What to do |
| - | - | - | - |
| 400 | `amount_below_minimum` | A `DEPOSIT` amount is below the minimum (1 USDC). `details` gives the minimum. | Deposit more. |
| 400 | `invalid_amount` | A `DEPOSIT` amount is above the per-request limit (1,000,000,000 USDC). `details` gives the limit. | Split the deposit. |
| 403 | `actions_not_enabled` | Transaction building is not enabled for your API client. | Ask Kamui to enable it. |
| 403 | `wallet_not_allowed` | The vault's allow list (`isAllowed`) does not accept the sender, or the receiver of a deposit. Build only. | The wallet cannot use this vault. |
| 409 | `vault_paused` | The vault is paused: it takes no deposits and no redeem requests. Build only. | Try again later. |
| 409 | `deposits_unavailable` | The vault does not accept synchronous deposits now (sync mode, or the NAV is being updated). Build only. | Try again later. |
| 409 | `deposit_cap_reached` | The deposit would exceed the vault's cap, counting the deposits waiting for settlement. Build only. | Deposit less, or later. |
| 409 | `redeem_request_already_pending` | The sender already has a redeem request waiting for settlement in this vault. Build only. | Wait until it settles. |
| 422 | `insufficient_balance` | The sender holds less USDC than the deposit. Build only. | Deposit less. |
| 422 | `insufficient_shares` | The sender holds fewer shares than the redeem request. Build only. | Request fewer shares. |
| 422 | `simulation_failed` | A built transaction reverts in simulation. `details` names the transaction (`transactions.<index>`) and the error. | Fix the cause, then build again. |
| 503 | `actions_disabled` | Transaction building is switched off for every client. The read actions still answer. | Retry later. |

The `code` list in the API reference also has codes the API does not answer today (`invalid_address`, `unsupported_chain` and `jurisdiction_restricted`). An invalid address answers `400 invalid_request`. Handle any code you do not know by its HTTP status.

Errors are never cached (`Cache-Control: no-store`), and neither are successful responses.


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