401, 403, 429 и 503: с чего начать разбор ошибки API

Сначала соберите сведения об ошибке

Запишите метод, адрес конечной точки, код ответа, время и идентификатор запроса, если он есть. Прочитайте тело ошибки и относящиеся к ней заголовки. Выясните, кто вернул ответ: само приложение API, шлюз или защитный прокси. Один и тот же код у них может появляться по разным причинам.

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

Уточнить причину перед повтором

При 401 проверьте учётные данные и схему аутентификации. При 403 — права и запрашиваемый ресурс. Повтор того же запрещённого запроса обычно не устраняет причину.

401 и 403 требуют разных действий

При 401 проверьте наличие и срок действия учётных данных, а также ожидаемую схему, например Bearer. Корректный ответ 401 включает WWW-Authenticate. Если API поддерживает обновление токена, выполните его один раз и повторите запрос один раз. Бесконечное обновление не исправит неверные учётные данные.

При 403 проверьте роль пользователя, конкретный ресурс и разрешения API. Учётная запись может иметь право читать, но не изменять данные. Запрет также может исходить от прокси, например по IP или региону. Новый токен сам по себе не добавляет недостающих прав: ориентируйтесь на тело ошибки и правила сервиса.

Повторять управляемо

Для 429 и 503 учитывайте Retry-After, если он передан, и ограничивайте число повторов. Сначала убедитесь, что повтор операции безопасен: запись с тайм-аутом могла уже выполниться. Сохраняйте идентификаторы запросов, но не секреты.

Что означает Retry-After

429 может относиться к квоте пользователя, IP или общему лимиту нескольких клиентов — это зависит от сервиса. В условном ответе ниже Retry-After: 30 означает ожидание 30 секунд перед новой попыткой. Вместо числа сервер может передать дату HTTP; реальный клиент должен учитывать оба варианта.

Уменьшите параллелизм и согласуйте повторы между процессами, которые расходуют одну квоту. При 503 дополнительно проверьте состояние сервиса и шлюза. Уважайте Retry-After; если его нет, увеличивайте интервалы с небольшим случайным разбросом и ограничивайте общее время. Массовые повторы во время перегрузки могут продлить сбой.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Нет ответа — не всегда значит, что операция не выполнена

Допустим, запрос создания задания или платежа завис после того, как сервер его принял. Повтор может создать дубликат, хотя первый ответ до клиента не дошёл. Для записи используйте предусмотренный API механизм идемпотентности или сначала проверяйте состояние операции. Не придумывайте заголовок идемпотентности, который сервис не поддерживает.

Практичный клиент разделяет постоянные проблемы авторизации и временные сбои, ограничивает попытки и сохраняет причину остановки. Повторить GET обычно проще, чем POST, но окончательное правило задаёт API. Для разбора передавайте время, адрес, статус и идентификатор запроса, удалив секреты.