Errors share a single body shape (Error schema): { "statusCode": 400, "message": "INSUFFICIENT_BALANCE", "error": "Bad Request" }. For request validation errors message is an array of strings, one per invalid property.
Business-rule refusals a client is expected to handle return a stable code as message: match on equality, a code is never reworded. Among them: INSUFFICIENT_BALANCE (wallet does not cover the price), PAYMENT_METHOD_NOT_ALLOWED (your Account's billing does not allow ordering through the API, contact your account manager), ALREADY_CANCELLED_ORDER, ALREADY_REFUNDED_ORDER, CANNOT_CANCEL_FULFILLED_ORDER, CANNOT_CANCEL_REPLACED_ORDER, ERROR_REFUNDING_ORDER.
400- invalid request, or a business rule refused it (seemessage)401- missing / invalid access token orX-App-Identifier403- your role is not allowed to call this endpoint404- the resource does not exist or does not belong to your Account409- the resource is in a state that does not allow the operation500- unexpected error, contact support with the request time
Retries: order creation endpoints are not idempotent. Do not blindly retry a timed-out or 5xx purchase — first check GET /orders or GET /subscriptions to see whether it was created. Cancellation endpoints are safe to retry.