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

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

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

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

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

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

{
  "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:

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 з попередньої відповіді:

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>"

Відповідь:

{
  "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). Вивантаження залишків повністю — див. Вивантаження залишків і цін на сайт.

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

Форма тіла помилки залежить від методу, тому обробляйте насамперед 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-пагінації дорожчі. Рішення: для залишків користуйтеся курсорним методом, для інших списків звужуйте вибірку фільтрами за періодом.