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

Статья Обзор называет соглашения, которым следует каждая операция. Эта страница добавляет к ним, что запрос может нести помимо тела и что несёт обратно ответ, как читается список длиннее одной страницы и сколько запросов может отправить ключ.

Заголовки

В ответах на запросы с 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 — что он значит и что делать.