Help / Developers

Errors

Every refusal has a status, a category, a code and a plain message. Code against the status and the code, not the words.

A refused call answers with an HTTP status and this body:

{
  "detail": {
    "category": "conflict",
    "message": "The transaction changed since it was read; the current transaction is returned.",
    "code": "stale",
    "transaction": { "id": "…", "version": 4 }
  }
}

category is the kind of refusal: conflict, not_found, validation, invalid_request, rate_limited, unavailable or refused.
code names the exact reason, such as stale, idempotency_key_busy, buyer_exists or phone_invalid. It is not on every error.
message is plain words for a person. It can change.
A refusal about a transaction adds transaction, the transaction as it now stands. A refusal that can be retried adds retry_after_s.

Statuses #

Status	When
403	The key's member may not do this. Or the transaction belongs to a branch the member does not work at (`not_your_branch`).
404	There is no such transaction or customer, or it belongs to another shop. The two look the same.
409	The move is not allowed now. The transaction changed since you read it (`stale`). The move does not fit its state (`not_allowed`). A request is waiting for the seller (`pending`). A refund has no payment behind it (`not_paid`). The customer's cart is in use. An `Idempotency-Key` is still held by a first request that has not finished (`idempotency_key_busy`). A customer with that phone already exists in the app's own form (`buyer_exists`), or another customer already has that `external_ref` (`external_ref_taken`).
422	The request is wrong. A field is missing or unknown. A phone number is not one (`phone_invalid`). An amount is sent on something other than a refund (`amount_invalid`). A reason is not one of the shop's `reject_reasons` (`reason_invalid`). The `Idempotency-Key` was used before with a different body. `If-Match` and the body's `version` differ (`version_mismatch`). A refund is more than what is left.
429	Too many requests, or the shop's allowance for today is used up. See Rate limits.
502	A refund could not be completed with the payment provider (`refund_failed`, `refund_unknown`).
503	Transactions are not available for a moment. Try again.

A call that went through with problems #

Some problems are not errors. A cart or a placing can answer 200 with a problems list. Each problem has a kind, such as unknown_offering, not_enough, price_changed or slot_unavailable, the item's offering_key, and facts. The API has no sentences for these. Word them yourself.

A refund that may have happened #

If a refund fails with the code refund_unknown, the payment provider did not answer, so the money may have gone back. Tejas is checking. Do not send the refund again.

A stale decision #

When you decide on an old version, the answer is 409 with the code stale and the transaction as it now is. Read it. Decide again if the move still makes sense.

Did this page help?

Last checked: 2026-11-07