Заголовки, сторінки й ліміт запитів

Стаття Огляд називає домовленості, яких дотримується кожна операція. Ця сторінка додає до них, що запит може нести крім тіла і що несе назад відповідь, як читається список, довший за одну сторінку, і скільки запитів може надіслати ключ.

Заголовки

У відповідях на запити з API-ключем Retry-After приходить із відповіддю 429 через ліміт запитів (нижче), із відповіддю 503 з кодом pool_exhausted, коли провайдер попросив свою останню спробу зачекати, і з відмовою у зміні бюджету, яка надто довго чекала викликів, що йдуть цим бюджетом.

Список сторінками

Список, який читають посторінково, відповідає по одній сторінці й додає до неї meta: limit, розмір сторінки, і next_cursor.

curl "https://api.slen.ai/api/v1/ledger-entries?limit=2" \
  -H "Authorization: Bearer $SLEN_API_KEY"

{
  "data": [
    {
      "entry_id": "74442131708452864",
      "reservation_id": "74442097331195904",
      "type": "usage_capture",
      "amount": "0.00014100",
      "currency": "USD",
      "metadata": {
        "input_tokens": 420,
        "output_tokens": 130,
        "is_partial": false,
        "estimated_cost": "0.00018300",
        "reserved_amount": "0.00021960"
      },
      "created_at": "2026-10-02T08:40:15+00:00"
    },
    {
      "entry_id": "74442097335390208",
      "reservation_id": "74442097331195904",
      "type": "reservation_hold",
      "amount": "0.00021960",
      "currency": "USD",
      "metadata": {
        "model_code": "gpt-4o-mini",
        "estimation_strategy": "maximum",
        "safety_multiplier": "1.200"
      },
      "created_at": "2026-10-02T08:40:12+00:00"
    }
  ],
  "meta": {
    "limit": 2,
    "next_cursor": "74442097335390208"
  }
}

• limit задає розмір сторінки: від 1 до 100, 30, якщо ви його не надіслали, — 50 для списку клієнтів.

• Щоб прочитати наступну сторінку, надішліть той самий запит знову, вказавши в cursor значення next_cursor сторінки, яка у вас є. Більше нічого не змінюйте, інакше наступна сторінка виявиться сторінкою іншого списку.

• На останній сторінці next_cursor дорівнює null. Сторінка завдовжки рівно limit однаково несе курсор, тож кінцем списку може виявитися й сторінка з порожнім data і null.

• Курсор — значення, яке надсилають назад, а не складають.

Списки операцій, холдів і записів реєстру читають ще й вікно часу — не довше за сім днів. Як саме, каже сторінка кожного з цих ресурсів.

Чотири списки можна читати ще й за номером сторінки, з кількістю їхніх рядків: операції, виконання флоу, холди й записи реєстру. Надішліть page замість cursor, і в meta замість next_cursor прийдуть page, limit, total і anchor — як саме, показує розділ Пошук і нумеровані сторінки.

Ліміт запитів

Ключ може надіслати 120 запитів за хвилину, якщо сервіс не налаштовано інакше. Хвилина починається з першого запиту ключа. Рахується кожен запит, який ліміт пропустив, зокрема той, на який відповіли помилкою. У людини, що увійшла в консоль, свій ліміт. Перевірки стану /health і /ready не рахуються.

Кожна відповідь несе два заголовки ліміту: сам ліміт і те, що від нього лишилося, — відповідь нижче показує їх після Retry-After. Запит понад ліміт не виконується. На нього відповідають 429 з кодом rate_limit_exceeded, заголовком Retry-After — секундами до кінця хвилини — і моментом, коли вона скінчиться, у секундах Unix.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790932877
X-Request-Id: 3f6c1a52-8f0e-4c1b-9a57-1d2e6b7c9f10

{"error":{"code":"rate_limit_exceeded","message":"API rate limit exceeded","request_id":"3f6c1a52-8f0e-4c1b-9a57-1d2e6b7c9f10"}}

Зачекайте стільки, скільки каже Retry-After, і надішліть запит знову. Одна операція має ще й свій, менший ліміт: перевірку підключення до провайдера, POST /v1/provider-connections/{id}/test, можна надіслати шість разів за хвилину.

Що читати далі

• Огляд — базова адреса, форма відповіді й помилки, як записуються значення.

• Ідемпотентність — яким операціям потрібен ключ і чим відповідають на повтор.

• Коди помилок — кожен код API — що він означає і що робити.