Ошибки API и что они означают
Что обычно означает каждый HTTP-статус от API Didit на практике - 401 и 403 из-за ключей и прав доступа, проблемы с балансом в духе 402, лимиты 429 и как читать тело ошибки.
Читайте тело ответа. Ошибки Didit содержат сообщение и часто код с деталями, который называет реальную проблему - сам по себе статус редко всё объясняет. 401 означает проблему с ключом, 403 - права доступа или окружение, 429 - ограничение частоты запросов, а ошибка баланса связана с кредитами, а не с кодом.
#Сначала читайте тело ответа
HTTP-статус говорит о категории проблемы. Тело ответа говорит о том, что произошло на самом деле. Почти каждый потраченный впустую час отладки интеграции с API уходит на угадывание статус-кода, хотя ответ был в ответе, который просто отбросили.
- Отключённый или ключ не от того приложения - обычная причина ошибки 401.
- Last used показывает, действительно ли приходит тот ключ, который вы отправляете.
- Смените секрет, если ключ мог утечь - 401 лучше, чем взлом.
Логируйте полное тело ошибки - статус, заголовки и содержимое - при каждом неудачном вызове, в любом окружении. Это понадобится, а восстановить это позже намного сложнее.
#Что обычно означает каждый статус
| Статус | Обычная причина |
|---|---|
| 400 | Некорректный запрос - отсутствует обязательное поле, неверное значение enum, неправильная структура вложенного объекта |
| 401 | Аутентификация не удалась. Заголовок x-api-key отсутствует, повреждён или содержит невалидный ключ |
| 403 | Аутентификация прошла, но действие не разрешено. Неверное окружение, права, которых нет у вашего ключа, или функция, не включённая для вашего аккаунта |
| 404 | Ресурс не существует - либо существует в другом приложении, чем то, к которому относится использованный ключ |
| 409 | Конфликт с текущим состоянием - например, действие, которое уже было выполнено |
| 422 | Запрос был корректно оформлен, но значения не прошли проверку - это ошибка валидации, а не синтаксиса |
| 429 | Превышен лимит запросов. См. ниже |
| 5xx | Проблема на стороне Didit. Повторите запрос с задержкой и проверьте status.didit.me |
#401 против 403 - различие, которое экономит время
401 означает, что ключ вообще не был принят. Проверьте, что вы отправляете заголовок x-api-key, что в значении нет лишних пробелов или кавычек, и что вы случайно не вставили секрет подписи webhook вместо API-ключа - это разные вещи, и такая ошибка встречается часто.
403 означает, что ключ действителен, но этот вызов не разрешён. Три причины по порядку:
- Несоответствие окружения. Поля только для sandbox (например,
sandbox_scenario) отклоняются в боевом приложении, и наоборот. Боевое и sandbox-окружение - это разные приложения с разными ключами. - Отсутствует право доступа. Для некоторых операций нужны права, которых нет у вашего ключа или роли. Если вам нужны права на создание и управление сессиями, которых у вас нет, это вопрос к поддержке, а не к исправлению кода.
- Функция не включена. Некоторые возможности подключаются отдельно для каждой организации. Если вы получаете 403 на функцию, которая, как вам кажется, должна быть доступна, стоит уточнить это, прежде чем переписывать вызов.
Отличить sandbox-ключ от боевого просто по внешнему виду нельзя, поэтому храните их под явно разными именами в вашем хранилище секретов и никогда не держите в одной переменной окружения "какой ключ сейчас актуален". Боевой ключ в тестовом окружении тратит настоящие кредиты.
#404 там, где ресурс должен существовать
Если сессия или воркфлоу возвращает 404, а вы уверены, что они существуют, обычно дело в том, что они существуют в другом приложении, чем то, под которым вы аутентифицировались. Ресурсы привязаны к своему приложению; ключ приложения А не увидит сессии приложения Б.
#Ошибки баланса и кредитов
Вызов, который не проходит из-за нехватки кредитов, - это не ошибка кода. В воркфлоу есть платная функция, и вашего баланса на неё не хватает. Это самая частая жалоба вида "API сломался", и причина почти всегда - white label, AML или NFC в воркфлоу, который ожидался бесплатным. См. как исправить ошибку "недостаточно кредитов".
#Ограничение частоты запросов (429)
Лимиты применяются по идентификатору - вашему x-api-key или IP-адресу клиента, если ключ не передан - с независимым счётчиком для каждой области действия в скользящем окне 60 секунд.
Значения по умолчанию:
| Область | Методы | Лимит |
|---|---|---|
| Обычное чтение | GET | 600 / мин |
| Обычная запись | POST, PATCH, DELETE | 300 / мин |
У некоторых особо нагруженных эндпоинтов есть более строгие лимиты в дополнение к общему, и 429 возвращает та область, чей счётчик исчерпался первой. Полная таблица: ограничение частоты запросов.
Обрабатывайте 429 с экспоненциальной задержкой и случайным разбросом. Плотный цикл повторов при превышении лимита только усугубляет проблему и может держать вас в ограничении бесконечно долго.
Обычно источник 429 - пакетные задания: ночной импорт, который создаёт несколько сотен сессий за пару секунд. Распределяйте нагрузку во времени, а не поднимайте параллелизм, пока ошибки не прекратятся.
#Коды ошибок на уровне отдельных функций
Помимо HTTP-статусов, отдельные проверки возвращают собственные коды с деталями для проблем на уровне провайдера - например, интеграция с реестром, у которой нет доступа к конкретному продукту в конкретной стране. Когда вы получаете такой код, он точно называет ситуацию, поэтому цитируйте его, когда обращаетесь с вопросом.
Если в ответе отсутствует код, который вы ожидали увидеть по каталогу, об этом стоит сообщить, а не обходить проблему - отсутствующий код это реальный пробел, и он усложняет жизнь следующему, кто с этим столкнётся.
#Пустой ответ - это не успех
Проверка через провайдера, вернувшая пустое тело, - это не то же самое, что чистый результат. Обрабатывайте "нет данных" как отдельный случай в вашем коде, а не приравнивайте его к успеху - особенно для проверки по базам данных и скрининга кошельков, где неподключённый сервис и настоящее отсутствие совпадения могут выглядеть одинаково со стороны.
#Тестирование путей ошибок
Sandbox детерминированно вызывает конкретные сбои, и это единственный разумный способ протестировать обработку ошибок. См. тестирование в sandbox.