Ошибки и повторные запросы

Единый формат ошибки

{
  "error": {
    "code": "insufficient_credits",
    "message": "Недостаточно запросов на балансе.",
    "request_id": "req_example"
  }
}

Ответ содержит заголовок X-Request-ID. Сохраняйте его при ошибке и передавайте поддержке. Текст сообщения предназначен человеку, логику клиента стройте по HTTP-статусу и error.code.

HTTP	Код	Действие
422	invalid_request	Исправьте параметры запроса
401	invalid_api_key / api_key_revoked	Проверьте ключ или создайте новый
403	invalid_api_key	Подтвердите email аккаунта
402	insufficient_credits	Пополните баланс пакетом
429	rate_limit_exceeded	Подождите Retry-After секунд
409	idempotency_conflict / idempotency_in_progress	Используйте исходное тело либо новый ключ
503	carrier_unavailable	Все службы завершились технической ошибкой; запрос возвращён
500 / 503	internal_error	Повторите позже с тем же Idempotency-Key

Ошибки аутентификации, валидации, нехватка баланса и ограничения частоты не списывают запрос.

Частичный результат

Если хотя бы часть перевозчиков ответила, API возвращает HTTP 200. Доступные тарифы находятся в rates, причины по остальным — в unavailable. Не отклоняйте весь результат из-за непустого unavailable.

Возможные причины: timeout, circuit_open, not_configured, unavailable, invalid_response, no_rates, postal_code_required, declared_value_required, ambiguous_city, rate_limited, upstream_auth_error, invalid_request, upstream_error. Новые значения могут добавляться: неизвестную причину обрабатывайте как недоступность конкретной службы.

Идемпотентный повтор

Передайте уникальный Idempotency-Key (например, UUID) для операции расчёта. При повторе с тем же ключом и параметрами сервер вернёт сохранённый результат без нового списания. Область ключа — аккаунт. Не используйте один ключ для разных отправлений.

Idempotency-Key: 5d0b7008-59de-43ef-a14d-f8d0ca0a45ae

Конфликт тела запроса возвращает 409. Повтор во время ещё выполняющегося расчёта также может вернуть 409; подождите перед повтором. Хранение ключа ограничено 24 часами: после этого не полагайтесь на повтор без списания.

Повторы без перегрузки

Для 429 следуйте Retry-After. Для временных 503 применяйте увеличивающуюся задержку с небольшим случайным отклонением. Ошибки 401, 402 и 422 не исправляются автоматическим повтором.

Стоимость и сроки являются расчётными. Фактическая стоимость может отличаться от расчётной в зависимости от условий перевозчика, характеристик груза и договора отправителя. Доставометр не является перевозчиком, не заключает договор перевозки, не принимает груз и не отвечает за фактический срок доставки.