# Ліміти API, пагінація і помилки

URL: https://bimpsoft.com/help/developers/api-limits/
Updated: 2026-11-06

> API Bimp приймає до 15 запитів на секунду з одного IP; надлишок стає в чергу на 30 запитів, а що не вмістилося — отримує відповідь 429. Списки пагінуються трьома способами: offset/count, page/pageSize і курсором limit/lastId. Помилки мають різні форми залежно від методу.

## Який ліміт запитів до API

Максимум — 15 запитів на секунду з одного IP-адреса. Запити понад ліміт не відхиляються одразу, а стають у чергу розміром 30 запитів і обробляються в наступні секунди. Запити, які не вмістилися в чергу, повертаються з помилкою HTTP 429.

Для масових вивантажень тримайте швидкість нижче 15 запитів на секунду і виконуйте запити послідовно, а не в кілька паралельних потоків з одного IP.

## Що робити з відповіддю 429

Відповідь 429 означає перевищення ліміту. Її тіло має таку форму:

```json
{
  "success": false,
  "error": {
    "code": 429,
    "message": "<message>",
    "details": "<details>",
    "retryAfter": 1
  }
}
```

Зачекайте `error.retryAfter` і повторіть запит. Якщо 429 повторюється, збільшуйте паузу експоненційно (1 с, 2 с, 4 с).

## Які види пагінації є в API

API використовує три види пагінації, залежно від методу.

| Вид | Параметри | Ліміти за специфікацією | Де використовується |
|---|---|---|---|
| Offset | об'єкт `pagination` з `offset` і `count` у тілі `POST` | `offset` від 0; `count` за замовчуванням 10, максимум 100 | більшість методів `readList` і `readExternalIdsList` |
| Page | `page` і `pageSize` у рядку запиту `GET` | `page` за замовчуванням 1; `pageSize` за замовчуванням 50, максимум 100 | `/org2/inventory/api-readList` |
| Cursor | `limit` і `lastId` у рядку запиту `GET` | `limit` за замовчуванням 50, максимум 200 | `/org2/inventory/api-readList/cursor`, `/org2/inventory/kits/api-readList/cursor` |

### Offset-пагінація

Передайте `pagination` у тілі запиту і збільшуйте `offset` на `count`, доки відповідь не стане коротшою за `count`:

```bash
curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-readList \
  -H "access-token: <COMPANY_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"pagination": {"offset": 100, "count": 100}}'
```

Максимальне значення `count` дивіться в довіднику конкретного методу.

### Курсорна пагінація

Курсорна пагінація призначена для великих наборів (понад 5000 позицій). Параметри `orgId` і `warehouseId` обов'язкові. Першим запитом не передавайте `lastId`, а в наступних підставляйте `data.next_cursor` з попередньої відповіді:

```bash
curl -G https://app.bimpsoft.com/org2/inventory/api-readList/cursor \
  -H "access-token: <COMPANY_ACCESS_TOKEN>" \
  --data-urlencode "orgId=<ORG_UUID>" \
  --data-urlencode "warehouseId=<WAREHOUSE_UUID>" \
  --data-urlencode "limit=200" \
  --data-urlencode "lastId=<NEXT_CURSOR>"
```

Відповідь:

```json
{
  "success": true,
  "data": {
    "items": [
      { "productId": "<UUID>", "barcode": "", "article": "A-100", "quantity": 12, "reserved": 2, "available": 10, "batchId": null }
    ],
    "next_cursor": "<UUID>",
    "next_cursor_batch_id": null
  }
}
```

Якщо ввімкнено `byBatches=true`, залишки розбиваються за партіями; тоді разом із `lastId` передайте `lastBatchId` зі значення `next_cursor_batch_id` (пропустіть, якщо воно `null`). Вивантаження залишків повністю — див. [Вивантаження залишків і цін на сайт](https://bimpsoft.com/help/developers/sync-stock-and-prices/).

## Як виглядають помилки

Форма тіла помилки залежить від методу, тому обробляйте насамперед HTTP-код, а потім тіло.

| Код | Коли | Форма тіла за специфікацією |
|---|---|---|
| 422 | помилка валідації запиту | `{"error": "...", "message": "...", "details": "..."}` (`error` і `message` обов'язкові) |
| 404 | об'єкт не знайдено (наприклад, `/org2/inventory/api-read/{productHex}/stock`) | `{"status": "error", "message": "..."}` |
| 429 | перевищено ліміт запитів | `{"success": false, "error": {"code": 429, "message", "details", "retryAfter"}}` |

Успішні відповіді мають вигляд `{"success": true, "data": ...}`. Деякі методи повертають у `data` значення `null`, коли об'єкта немає (наприклад, `readByExternalId`).

## Типові проблеми

**Масове вивантаження періодично повертає 429.** Причина: перевищено 15 запитів на секунду з одного IP, а черга на 30 запитів заповнилася. Рішення: надсилайте запити послідовно з паузою і повторюйте після `retryAfter`.

**Offset-вивантаження великого списку працює дедалі повільніше.** Причина: глибокі сторінки offset-пагінації дорожчі. Рішення: для залишків користуйтеся курсорним методом, для інших списків звужуйте вибірку фільтрами за періодом.

## FAQ

**Скільки запитів на секунду дозволяє API Bimp?**

До 15 запитів на секунду з одного IP. Надлишок потрапляє в чергу розміром 30 запитів і обробляється в наступні секунди; запити, що не вмістилися в чергу, повертаються з помилкою 429.

**Що робити з відповіддю 429?**

Зачекайте і повторіть запит. Тіло відповіді 429 містить поле error.retryAfter. Надалі тримайте частоту запитів нижче 15 на секунду.

**Яку пагінацію обрати для вивантаження всіх залишків?**

Курсорну: GET /org2/inventory/api-readList/cursor. Вона призначена для великих наборів даних і не сповільнюється на глибоких сторінках.