Errors - Kamui

Every error response has this body:

{
  "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.
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.	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 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.