Reference

Error Reference

All Kifly agent endpoints return structured JSON errors:

{
  "error": "error_code",
  "message": "Human-readable explanation",
  "details": {}
}

details contains context specific to the error (e.g., the delivery zones that rejected the address).

HTTP status codes

Status	Meaning	What to do
`400`	Bad request — missing or invalid field	Fix the request body; do not retry as-is
`401`	Missing or invalid API key	Check your `Authorization: Bearer kfa_live_…` header
`402`	Payment required	Follow the MPP challenge-response flow
`403`	Forbidden — resource belongs to a different token	Do not retry
`409`	Idempotency conflict — same key, different request body	Use a new `Idempotency-Key`
`422`	Validation error — semantically invalid	Read `details` for the specific field
`429`	Rate limit exceeded	Wait for `retry-after` seconds
`503`	Upstream dependency temporarily unavailable	Retry after `retry_after_seconds`

Error codes

Authentication

Code	Description
`invalid_api_key`	The Bearer token is not recognized
`api_key_revoked`	The token exists but has been revoked by the seller

Cart

Code	Description
`cart_not_found`	No cart with the given ID under your token
`cart_locked`	Checkout is already in progress; wait and retry
`cart_already_completed`	The cart was already purchased; create a new cart
`missing_idempotency_key`	`Idempotency-Key` header is required
`idempotency_conflict`	Same key used with a different request body

Checkout / Payment

Code	Description
`shipping_address_required`	Call `set_shipping_address` before `checkout`
`delivery_not_available`	Buyer's address is outside the seller's delivery zones
`payment_failed`	SPT verification or Stripe settlement failed
`x402_not_configured`	`X-Payment` sent but x402 is not enabled

Upstream

Code	Description
`upstream_unavailable`	A required upstream service is temporarily down
`checkout_engine_unavailable`	Commerce engine unreachable; cart state is safe, retry checkout

Retry strategy

For 503 responses, use exponential backoff starting at the retry_after_seconds value in the body:

{
  "error": "upstream_unavailable",
  "retry_after_seconds": 30
}

For 429 responses, wait for the value in the Retry-After header. For all other errors, fix the request before retrying.

Always reuse the same Idempotency-Key when retrying the same logical operation — this guarantees exactly-once semantics even if the network drops after the server commits.

Rate limits

Endpoint	Limit
`/api/mcp`	120 req / 60 s per token
`/api/agent/*`	60 req / 60 s per token
`/api/agent/feedback`	10 req / 60 s per token

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