Documentation sections
Documentation/API
Errors and limits
Error format, response codes, rate limits
Error format
All errors share a single format. The message field is a string or an array of strings: validation errors list every problem with the request body at once. The error field is absent in some responses (for example, 429) - rely on statusCode.
{
"statusCode": 400,
"message": [
"Минимальная сумма - 100 копеек (1 рубль)"
],
"error": "Bad Request"
}Response codes
| Code | When it occurs |
|---|---|
| 400 | The request failed validation: the body, query parameters, or an identifier in the path. The reasons are in message (a string or an array of strings). |
| 401 | The X-Api-Key header is missing, the key is invalid, or the shop is not active. |
| 404 | The payment was not found or belongs to another shop. |
| 409 | Conflict: a payment with this orderId already exists, the payment method is not available to the shop, or cancellation is impossible because the customer has already started paying. |
| 429 | Rate limit exceeded - retry later, ideally after a pause. |
| 5xx | Internal error. The outcome of the operation is unknown - do not blindly retry the request; check the payment status first (see below). |
Network failures: do not create duplicates
If you received a 5xx while creating a payment, or never got a response at all, the outcome is unknown: the payment may or may not have been created. The correct procedure:
- fetch the payment by your orderId;
- if you get a 404, the payment does not exist - create it again with the same orderId;
- if the payment is found, use its payUrl - there is nothing to create.
The API has a built-in safety net: creating a payment again with the same orderId returns 409, so you cannot duplicate a payment even by mistake.
Rate limits
Up to 600 requests per minute per API method; the limit is counted per API key. The exception is GET /api/v1/balance: it has its own limit of 60 requests per minute. Exceeding a limit returns 429; the window resets within a minute. There is also an overall cap of 2000 requests per minute from a single IP address across the whole API - keep it in mind if several shops run from one server.
Do not poll payment statuses in a loop: the result arrives faster and more reliably via a webhook. Keep polling as a fallback.
Didn't find an answer
Email us at support@tabpay.org or message us on Telegram at @tabpaysupport - we will help with your integration.