Error Reference

Every agent-facing failure returns the same envelope. Branch on code and fix. Never parse error or message — that prose is written for people and is reworded freely.

{
  "error": "cart_not_found",
  "code": "CART_NOT_FOUND",
  "fix": "change_input",
  "retryable": false,
  "docs": "https://kifly.ai/docs/errors#cart_not_found",
  "request_id": "req_0b4f…"
}

Always present: error, code, fix, retryable, docs, request_id. Present where they add something: message, next_step, required_scope, retry_after_seconds, details.

code decides the HTTP status, not the other way round. One code is always returned with the same status, so a client that branches on code never has to disambiguate by reading the status too.

request_id rides every failure, in the body and in the x-request-id header. Quote it in a bug report and we can find the exact request.

On MCP, the identical detail arrives as structuredContent on the tool result, alongside the human sentence. There is nothing to parse there either.

The machine-readable version of this page, generated from the same source, is at GET /api/agent/errors — 102 codes.

What to do, by fix

fix: "change_input" — Fix the request, then call again

The call will keep failing identically until an argument changes.

fix: "add_credential" — Get a credential, or a wider scope

The request itself is fine. See the OAuth metadata at /.well-known/oauth-authorization-server, which supports Dynamic Client Registration.

fix: "wait_and_retry" — Retry the same call later

Nothing is wrong with the request. Back off using retry_after_seconds where it is present, and reuse the same Idempotency-Key.

fix: "choose_another" — Pick a different item, variant or seller

This one cannot serve the request, however the call is phrased.

fix: "ask_human" — A human has to act

Surface it to the person you are acting for, or report it with submit_feedback.

fix: "none" — Nothing to do

The request reached a final state.

Common pitfalls (not errors — a valid 200 that isn't what you expected)

"My search only ever returns one seller's products." You're holding a seller API key (kfa_live_). It authenticates as that one store and is scoped to it at the database level — this is intentional (a seller key must never read another seller's catalog), not a bug, and it returns a normal 200 because from its own point of view the request succeeded. There is no way to widen a seller key's scope after the fact. If you need the whole network, switch to OAuth or a network key (kfn_live_) — see MCP Integration → Authentication.

Retry strategy

Retry when retryable is true. Use exponential backoff starting from retry_after_seconds where the body carries it, and the Retry-After header on a 429.

Always reuse the same Idempotency-Key when retrying — that is what makes a retry exactly-once even if the network drops after the server commits.

Rate limits

Responses include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset headers on every request.