Skip to content
KiukiPlatform
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

StatusMeans
200, 201, 202Done (201: made; 202: queued).
400Malformed: fix the request.
401No valid key.
402kiuki.com's payment can't pay for it.
403The key can't do this: the message says what is missing.
404No such record for your organisation.
409Valid, but can't be done now: the error code says why.
413Too large.
429Too fast: wait for Retry-After.
500Kiuki's fault: try again later.
503Nothing was done: the same request again in a moment is safe.

Codes

CodeStatusMeansWhat to do
bad_request400The 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_in401No API key was sent, or it isn't valid (wrong, or revoked).Send Authorization: Bearer kp_... with a key that works.
forbidden403The 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_found404There 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.
conflict409The request is valid but can't be done now.The message says why.
market_closed409The market isn't open for orders.GET /v1/markets lists the open ones.
unavailable409Some 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_expired409The quote's 10 minutes are up.Ask for a new quote: prices and stock may have changed.
quote_blocked409An 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_used409An order was already placed from this quote.Ask for a new quote for a new order.
external_ref_used409Your 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_unavailable409An origin in the quote no longer takes orders.Ask for a new quote.
out_of_stock409Stock ran out between the quote and the order; nothing was ordered.Ask for a new quote.
payment_refused402kiuki.com only: the payment named can't pay for this order.The message says why.
payment_used409kiuki.com only: the payment named already paid for another order.Use the shopper's own payment for each order.
not_cancellable409What 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_large413The body is over the endpoint's limit.Send less.
rate_limited429The key sent more requests than its rate allows.Wait as long as Retry-After says, then send it again.
internal500Something went wrong on Kiuki's side. It has been logged.Try again later; Kiuki looks into it.
stripe_unavailable503Stripe couldn't be reached, so nothing was done.Send the same request again in a moment.
payments_unavailable503Payments 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.