5. API errors

v2 errors use a JSON object with a numeric HTTP code and a message:

{
  "error": {
    "code": 400,
    "message": "Bad request"
  }
}

HTTP	Typical cause	Merchant action
400	Non-object or invalid JSON, a POST query string, missing or unsupported fields, wrong type or account format, invalid shop or URL.	Check the create schema and selected shop configuration.
401	Missing, inactive or v2-disabled API key; missing/invalid signature; source IP not allowed.	Check credentials, exact raw-body signature and IP allowlist.
403	Access denied by an authorization rule.	Contact your integration contact.
404	Transaction ID not found in your v2 scope, or unsupported v2 route.	Use a v2 transaction_id returned to your merchant.
409	order_id already used for this operation type with different request data, or by an incompatible legacy operation.	Compare with the original order. Retry its original request; use a new ID only for an intentionally separate operation.
422	Business rule such as shop currency mismatch or configured amount limit.	Correct the amount/currency or contact your integration contact.
503	Processing is temporarily unavailable.	Retry the same order_id after the service recovers.
500	Server error.	Retry the identical request and contact support if it persists.

Validation errors return 400 with "message": "Bad request"; they do not expose a per-field errors array. A v2 error does not use the v1 top-level message/code schema. For a timeout, connection loss, or uncertain create outcome, retry with the same order_id and original request data. If you already have transaction_id, query its status. Do not create a new order or switch to v1 to bypass uncertainty: contact your integration contact if reconciliation is needed.

HTTP 200 from create does not guarantee a successful financial result. An operation can already have FAILED status, for example after an applicable payment check. Retrieve its status and handle the result independently of the create HTTP code.

The signed PayIn browser page and return link are separate from these JSON API endpoints. An expired or changed link may return HTTP 403 in the browser; use the authenticated status API to check the payment.