Documentation
Errors
Every status and error code, and what to do about it.
Every error is JSON with a stable code to branch on and a message in plain English that is safe to show to a person:
{"error": "quote_expired", "message": "Quote 0b7e... expired at 2026-11-20T10:41:02Z. Ask for a new quote: prices and stock may have changed."}
A quote refused line by line also lists each line and why, in lines.
Statuses
| Status | Means |
|---|---|
| 200, 201, 202 | Done (201: made; 202: queued). |
| 400 | Malformed: fix the request. |
| 401 | No valid key. |
| 402 | kiuki.com's payment can't pay for it. |
| 403 | The key can't do this: the message says what is missing. |
| 404 | No such record for your organisation. |
| 409 | Valid, but can't be done now: the error code says why. |
| 413 | Too large. |
| 429 | Too fast: wait for Retry-After. |
| 500 | Kiuki's fault: try again later. |
| 503 | Nothing was done: the same request again in a moment is safe. |
Codes
| Code | Status | Means | What to do |
|---|---|---|---|
bad_request | 400 | The request is malformed: a field is missing, too long, or not what it should be. | Fix what the message names. Sending it again unchanged gets the same answer. |
not_signed_in | 401 | No API key was sent, or it isn't valid (wrong, or revoked). | Send Authorization: Bearer kp_... with a key that works. |
forbidden | 403 | The key can't do this: it lacks the scope the message names, its organisation isn't approved or is suspended, or it is another app's key. | Use a key with the scope named, or make one in the dashboard. |
not_found | 404 | There is no such record for your organisation (or no such endpoint). | Check the id. A sandbox key sees only the sandbox's records, and a live key only live ones. |
conflict | 409 | The request is valid but can't be done now. | The message says why. |
market_closed | 409 | The market isn't open for orders. | GET /v1/markets lists the open ones. |
unavailable | 409 | Some lines of the quote can't be bought now; lines lists each one and why (not on sale, not enough stock, stock data over an hour old). | Change the basket and ask again. |
quote_expired | 409 | The quote's 10 minutes are up. | Ask for a new quote: prices and stock may have changed. |
quote_blocked | 409 | An origin refused its shipment (minimum order not met, no delivery to the postcode, no rate card in force). | See the origin's blocked reason in the quote; change the basket. |
quote_used | 409 | An order was already placed from this quote. | Ask for a new quote for a new order. |
external_ref_used | 409 | Your external_ref is already an order placed from a different quote (or payment). | Use a new external_ref for a new order. The same request again returns the order it made. |
origin_unavailable | 409 | An origin in the quote no longer takes orders. | Ask for a new quote. |
out_of_stock | 409 | Stock ran out between the quote and the order; nothing was ordered. | Ask for a new quote. |
payment_refused | 402 | kiuki.com only: the payment named can't pay for this order. | The message says why. |
payment_used | 409 | kiuki.com only: the payment named already paid for another order. | Use the shopper's own payment for each order. |
not_cancellable | 409 | What you asked to cancel can't be: the order's shipments, or the shipment you named, are being picked or have gone. | Nothing to do: shipments already picked go out. |
too_large | 413 | The body is over the endpoint's limit. | Send less. |
rate_limited | 429 | The key sent more requests than its rate allows. | Wait as long as Retry-After says, then send it again. |
internal | 500 | Something went wrong on Kiuki's side. It has been logged. | Try again later; Kiuki looks into it. |
stripe_unavailable | 503 | Stripe couldn't be reached, so nothing was done. | Send the same request again in a moment. |
payments_unavailable | 503 | Payments aren't set up on this server, so nothing was done. | Send the same request again later. |
Retrying
A 503 means nothing was done: send the same request again in a moment. A timeout or a dropped connection means you don't know whether it worked. Placing an order and reporting a complaint are safe to send again with the same external_ref; for every other request, idempotency says what sending it again does.