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

Что можно повторить автоматически, когда нужен новый запрос и какие данные оставить в логах.

Ошибка API состоит из HTTP-статуса и стабильного error.code. Текст error.message предназначен человеку и может уточняться, поэтому ветвить код по нему нельзя.

Минимальный формат ошибки

{
  "error": {
    "code": "method_unavailable",
    "message": "Этот способ оплаты недоступен проекту",
    "details": null
  }
}

Сохраняйте HTTP-статус, error.code, x-request-id, идентификатор своей операции и время. Не записывайте API-ключ, карточные данные и полный заголовок авторизации.

Что делать по статусу

Ответ	Действие
`400`, `422`	Исправить данные; тот же запрос автоматически не повторять
`401`	Проверить или перевыпустить API-ключ
`403`	Проверить состояние проекта и доступ операции
`404`	Проверить идентификатор и принадлежность проекту
`409`	Не менять тело под прежним ключом; разобрать конфликт
`429`	Подождать `Retry-After`, затем решить о повторе на своей стороне
`500`, `502`, `504`	Повторить с тем же `Idempotency-Key` и тем же телом
Обрыв или тайм-аут	Результат неизвестен; повторить с тем же ключом

Идемпотентность

Все изменяющие методы требуют Idempotency-Key. Один ключ относится к одной операции и одному телу. Если первый ответ потерялся, повтор вернёт исходный результат, не выполняя операцию второй раз.

const key = `order-${order.id}`; // сохраните до запроса

await createInvoice(order, { idempotencyKey: key });
// После сетевого сбоя повторите с key и тем же телом.

idempotency_conflict означает, что под тем же ключом уже пришло другое тело или первая операция ещё не завершила фиксацию. Не обходите конфликт случайным новым ключом: сначала найдите исходную операцию.

Повторы в SDK

Node SDK повторяет сетевые ошибки и ответы 5xx, по умолчанию делает до трёх попыток и использует экспоненциальную задержку с разбросом. Ответы 4xx, включая 429, автоматически не повторяются; время ожидания доступно в PlateshkaApiError.retryAfterSeconds.

Следующий шаг

Если вы используете Node.js, подключите официальный SDK. Для точного списка ответов откройте нужный метод в API.