Лимиты и квоты REST API в Польше
Лимиты token-bucket, поведение при всплесках и обработка 429 для REST API Corp-Merch в Польше.
Архитектура — Лимиты на ключ и на маршрут в Польше
У каждого API-ключа свой token bucket на маршрут. По умолчанию: Standard 600 req/min на /v1/orders и /v1/invoices, 1 200 req/min на read-only; Pro 10x. Всплески до 2x допустимы в течение 10 секунд. В ответах есть заголовки X-RateLimit-Limit, -Remaining, -Reset. Выставление счетов через KSeF асинхронное и не лимитировано на submit — только на polling статуса. Расчёт VAT 23% без ограничений.
Как подключить — Ответы 429 и Retry-After
При превышении лимита возвращаем 429 Too Many Requests с заголовком Retry-After в секундах. Наши SDK обрабатывают это экспоненциальным backoff с jitter; в кастомном клиенте повторите ту же логику и не делайте busy-loop. Устойчивые 429 > 5 минут автоматически уведомляют нашу команду CS — мы скорее поднимем лимит, чем дадим вам падать.
Эксплуатация и пограничные случаи — Квоты и fair use
Поверх рейт-лимитов работают месячные квоты на заказы, счета и доставки webhook на тенант — рассчитанные под ваш контракт. Soft-квоты предупреждают на 80% и 100% через дашборд и email; hard-квоты (редкость, только trial) отклоняют с 402 Payment Required. Чтение каталога и polling статуса Krajowy System e-Faktur (KSeF) без ограничений на платных планах.
Частые вопросы
Можно ли получить лимит выше?
Да — на тарифах Pro и Enterprise мы поднимаем лимиты под ваши контрактные объёмы. Свяжитесь с поддержкой с профилем устойчивой нагрузки.
Read-only лимит выше?
Да — read-эндпойнты (GET /v1/catalog, GET /v1/orders) по умолчанию имеют 2x от лимита записей.
А webhook-и?
Их throughput идёт отдельным бюджетом — до 50/с на эндпойнт с backpressure; за входящий трафик вы не платите.
Как обрабатываются всплески?
Token bucket позволяет 2x burst в течение ~10 секунд, далее действует steady-state. Удобно для месячных батч-джобов.
Polling KSeF?
Polling /v1/invoices/{id} лимитируется как и другие read-запросы; для подтверждения KSeF рекомендуем webhook.