Guide

Errors

Error format, response codes and what to do about them.

All responses are JSON. Successful ones contain "status": "success", errors contain "status": "error" and message; some errors also have a machine-readable code.

JSON

{
  "status": "error",
  "code": "idempotency_key_reused",
  "message": "This idempotencyKey was already used for a different product"
}

Response codes

Code	When	What to do
400	Invalid ID, body or parameter.	Fix the request.
401 / 403	No key, invalid key, access or purchases disabled.	See “Authentication”.
402	Insufficient balance. No order created.	Top up and retry with the same key.
404	Product or order not found.	Check the ID.
409	The product can't be purchased.	Refresh the catalog, check availability.
413 / 415	Body over 10 KB or not JSON.	Fix the request.
422	idempotencyKey used for a different product.	Use a new key for a new purchase.
429	Rate limit exceeded.	Wait and slow down.
500	Internal error or `key_unavailable`.	Retry with the same idempotencyKey / fetch the order later.
502	The supplier didn't fulfill the order (`failed`). Money returned.	You may buy again with a new key.
503	Temporarily unavailable or maintenance (`maintenance_mode`).	Retry later.

Failure reasons (failureReason)

Returned in the purchase response message and in the failureReason field of a failed or cancelled order.

failureReason	Meaning
`insufficient_balance`	Insufficient balance.
`purchase_disabled`	Purchases are disabled for the client.
`product_unavailable`	The product can't be sold now: out of stock, or the supplier's price is outside the allowed range.
`fulfillment_failed`	The supplier didn't fulfill the order.
`fulfillment_cancelled`	The supplier cancelled or refunded the order.
`client_not_found`	Client not found.

The list may grow: treat an unknown value as a generic failure.