Кратко

  • После начала выполнения POST API v1 Stripe сохраняет код и тело первого ответа по ключу идемпотентности, включая 500. Повтор с тем же ключом получает сохранённый ответ, пока запись существует.
  • Код 500 оставляет последствия операции неопределёнными. Stripe может позднее согласовать работу и отправить webhook о созданном объекте, но ответ в кэше останется прежним. У API v2 другая логика повторов.

Ошибка на квитанции не обновляет бухгалтерию

Клиент получает 500, повторяет запрос с прежним ключом и снова видит 500. Можно решить, что сервис дважды отказал. В API v1 второй ответ может быть первой квитанцией, извлечённой из кэша. Stripe сохраняет результат после старта выполнения метода; заголовок Idempotent-Replayed: true показывает повторную выдачу. Счётчик ошибок без такого различия сообщает о числе квитанций, а не о числе неудачных операций.

За квитанцией может стоять действие. Stripe называет исход 500 неопределённым: побочные эффекты могли возникнуть. Во время восстановления компания пытается согласовать неудачные операции и может послать webhook для созданного объекта. Сохранённый ответ при этом не меняется. Согласование не гарантировано. Значит, статус HTTP и состояние объекта должны жить в отдельных графах одного журнала.

Связь между графами даёт локальный ID операции, созданный до первого вызова и записанный в метаданные ресурса.

После 500 команда ищет объект, изучает запрос в Dashboard и сверяет вебхуки после проверки подписи. Если результат ещё неизвестен, новый ключ идемпотентности может начать отдельную операцию. Служба поддержки и финансы должны спорить об одном ID, а не о двух разных снимках экрана.

В API v2 Stripe описывает иной повтор: успешное действие не повторяется, а неудачное или частично завершённое по возможности доводится до конца с обновлённым ответом. При переходе с v1 нельзя переносить старую инструкцию «повтори 500» без указания версии. Сначала установить контракт вызова, затем фактическое состояние объекта.

Источники