Обработка ошибок REST API в Польше
Ошибки RFC 7807 problem+json, стабильные коды и рекомендации по повторам для REST API в Польше.
Архитектура — RFC 7807 problem+json везде в Польше
Каждый ответ 4xx/5xx использует Content-Type: application/problem+json с полями: type (стабильный URI), title, status, detail, instance (request id) и расширяющие поля. type стабилен между версиями и ведёт в документацию с рекомендациями retry/fix. Всегда логируйте instance — поддержка пройдёт по нему end-to-end меньше чем за минуту.
Как подключить — Каталог типовых ошибок
invalid_vat (не совпало с VIES, retry после правки), invalid_sku (нет в каталоге Польша, правка), min_qty_violation (ниже MOQ, правка), invalid_tax_rate (не совпало с VAT 23%, правка), idempotency_conflict (одинаковый key, разный body, правка), insufficient_inventory (эскалация или ожидание), KSeF_unavailable (временно, retry с backoff). Полный каталог на /docs/errors.
Эксплуатация и пограничные случаи — Ошибки 5xx и идемпотентность
Ошибки 5xx означают, что запрос не зафиксирован. Мы логируем request id, поднимаем on-call и публикуем инциденты на странице статуса. Idempotency-ключи защищают вас: повторы с тем же ключом после 5xx никогда не списывают дважды. Наши SDK по умолчанию делают retry 5xx с экспоненциальным backoff (макс 3 попытки) — отключается, если нужен ручной контроль. Сбои Krajowy System e-Faktur (KSeF) приходят асинхронно по webhook с подсказками для retry.
Частые вопросы
Каталог ошибок стабилен?
Да — type URI версионируются и мы никогда не переназначаем код. Новые добавляются аддитивно.
Как корреляровать логи?
В каждом ответе есть instance = request id (cm-req-…). Передайте в поддержку — мы пройдём end-to-end меньше чем за минуту.
SDK или raw HTTP?
SDK бросают типизированные исключения, соответствующие type URI — обычно проще, чем парсить JSON. Raw HTTP тоже работает.
А валидационные ошибки?
422 с массивом errors, по одной записи на проблемное поле — со стабильным кодом и человекочитаемым сообщением.
KSeF_unavailable?
Временно — наш шлюз буферизует payload счёта и повторяет в KSeF. Об успехе сообщит webhook.