Работа в production

Ошибки API

HTTP-статусы, машинные коды и решения для каждого класса ошибок.

REST API v12 мин чтения

Структура ошибки

Принимайте решения по HTTP-статусу, code и pending, а не по тексту error: сообщение может меняться. Внешний прокси может вернуть HTML или пустое тело — сначала прочитайте текст и только затем безопасно разберите JSON.

JSON · example
{
  "code": "conflict",
  "error": "Purchase is still processing",
  "pending": true
}

Справочник ошибок

Справочник ошибок
HTTP / codeЧто проверить
400 · invalid_requestJSON, обязательные параметры, диапазоны и формат Idempotency-Key.
401 · invalid_api_keyКлюч полный, не отозван; аккаунт не заблокирован.
403 · forbiddenДоступ сервера отклонён. Нужна диагностика поддержки.
404 · not_foundМаршрут, ID заказа и его принадлежность аккаунту.
405 · method_not_allowedHTTP-метод соответствует контракту.
409 · conflictБаланс, maxPrice, наличие, статус заказа, pending и параметры повтора.
413 · payload_too_largeТело не больше 8192 байт.
415 · unsupported_media_typeContent-Type: application/json для POST.
429 · rate_limit_exceededПауза по Retry-After для общего бюджета аккаунта.
502 / 503 · service_unavailableВременная проблема сервера или соединения. Для покупки результат неизвестен.

pending — сигнал неопределённости

pending: true означает, что нельзя начинать новую покупку вместо текущей. Сохраните исходную операцию, проверьте историю и повторяйте только с прежними ключом и телом. Отсутствие pending при сетевой ошибке не доказывает, что списания не было.

Не нашли ответ на свой вопрос?Помощь с интеграцией