# Ошибки API и что они означают

Source: https://help.didit.me/ru/integration/api-errors
Updated: 2026-10-12

Читайте тело ответа: оно называет реальную проблему. 401 - ключ, 403 - права или окружение, 429 - лимит запросов, а ошибка баланса связана с кредитами.

**Читайте тело ответа.** Ошибки Didit содержат сообщение и часто код с деталями,
который называет реальную проблему - сам по себе статус редко всё объясняет. 401
означает проблему с ключом, 403 - права доступа или окружение, 429 - ограничение
частоты запросов, а ошибка баланса связана с кредитами, а не с кодом.

## Сначала читайте тело ответа

HTTP-статус говорит о категории проблемы. **Тело ответа** говорит о том, что произошло на самом деле. Почти каждый потраченный впустую час отладки интеграции с API уходит на угадывание статус-кода, хотя ответ был в ответе, который просто отбросили.

![Страница API-ключей в консоли Didit со статусом ключей и временем последнего использования](https://help.didit.me/screenshots/api-keys-light.webp)

*Большинство ошибок 401 и 403 объясняются на этой странице.*

Логируйте полное тело ошибки - статус, заголовки и содержимое - при каждом неудачном вызове, в любом окружении. Это понадобится, а восстановить это позже намного сложнее.

## Что обычно означает каждый статус

| Статус | Обычная причина |
|---|---|
| **400** | Некорректный запрос - отсутствует обязательное поле, неверное значение enum, неправильная структура вложенного объекта |
| **401** | Аутентификация не удалась. Заголовок `x-api-key` отсутствует, повреждён или содержит невалидный ключ |
| **403** | Аутентификация прошла, но действие не разрешено. Неверное окружение, права, которых нет у вашего ключа, или функция, не включённая для вашего аккаунта |
| **404** | Ресурс не существует - либо существует в другом приложении, чем то, к которому относится использованный ключ |
| **409** | Конфликт с текущим состоянием - например, действие, которое уже было выполнено |
| **422** | Запрос был корректно оформлен, но значения не прошли проверку - это ошибка валидации, а не синтаксиса |
| **429** | Превышен лимит запросов. См. ниже |
| **5xx** | Проблема на стороне Didit. Повторите запрос с задержкой и проверьте [status.didit.me](https://status.didit.me) |

## 401 против 403 - различие, которое экономит время

**401** означает, что ключ вообще не был принят. Проверьте, что вы отправляете заголовок `x-api-key`, что в значении нет лишних пробелов или кавычек, и что вы случайно не вставили секрет подписи webhook вместо API-ключа - это разные вещи, и такая ошибка встречается часто.

**403** означает, что ключ действителен, но этот вызов не разрешён. Три причины по порядку:

1. **Несоответствие окружения.** Поля только для sandbox (например, `sandbox_scenario`) отклоняются в боевом приложении, и наоборот. Боевое и sandbox-окружение - это разные приложения с разными ключами.
2. **Отсутствует право доступа.** Для некоторых операций нужны права, которых нет у вашего ключа или роли. Если вам нужны права на создание и управление сессиями, которых у вас нет, это вопрос к поддержке, а не к исправлению кода.
3. **Функция не включена.** Некоторые возможности подключаются отдельно для каждой организации. Если вы получаете 403 на функцию, которая, как вам кажется, должна быть доступна, стоит уточнить это, прежде чем переписывать вызов.

> **Tip:** Отличить sandbox-ключ от боевого просто по внешнему виду нельзя, поэтому
> храните их под явно разными именами в вашем хранилище секретов и никогда не
> держите в одной переменной окружения "какой ключ сейчас актуален". Боевой ключ
> в тестовом окружении тратит настоящие кредиты.

## 404 там, где ресурс должен существовать

Если сессия или воркфлоу возвращает 404, а вы уверены, что они существуют, обычно дело в том, что они существуют в **другом приложении**, чем то, под которым вы аутентифицировались. Ресурсы привязаны к своему приложению; ключ приложения А не увидит сессии приложения Б.

## Ошибки баланса и кредитов

Вызов, который не проходит из-за нехватки кредитов, - это не ошибка кода. Кредита вашего тарифа за месяц и баланса не хватает на проверку в воркфлоу. Это самая частая жалоба вида "API сломался", и причина обычно - white label, AML или NFC, которые увеличивают стоимость воркфлоу, либо проверка телефона на тарифе Free, которую его кредит не оплачивает. См. [как исправить ошибку "недостаточно кредитов"](https://help.didit.me/ru/billing-credits/not-enough-credits).

## Ограничение частоты запросов (429)

Лимиты применяются **по идентификатору** - вашему `x-api-key` или IP-адресу клиента, если ключ не передан - с независимым счётчиком для каждой области действия в скользящем окне 60 секунд.

Значения по умолчанию:

| Область | Методы | Лимит |
|---|---|---|
| Обычное чтение | `GET` | 600 / мин |
| Обычная запись | `POST`, `PATCH`, `DELETE` | 300 / мин |

У некоторых особо нагруженных эндпоинтов есть более строгие лимиты **в дополнение** к общему, и 429 возвращает та область, чей счётчик исчерпался первой. Полная таблица: [ограничение частоты запросов](https://docs.didit.me/integration/rate-limiting).

Обрабатывайте 429 с экспоненциальной задержкой и случайным разбросом. Плотный цикл повторов при превышении лимита только усугубляет проблему и может держать вас в ограничении бесконечно долго.

> **Note:** Обычно источник 429 - пакетные задания: ночной импорт, который создаёт
> несколько сотен сессий за пару секунд. Распределяйте нагрузку во времени, а не
> поднимайте параллелизм, пока ошибки не прекратятся.

## Коды ошибок на уровне отдельных функций

Помимо HTTP-статусов, отдельные проверки возвращают собственные коды с деталями для проблем на уровне провайдера - например, интеграция с реестром, у которой нет доступа к конкретному продукту в конкретной стране. Когда вы получаете такой код, он точно называет ситуацию, поэтому цитируйте его, когда обращаетесь с вопросом.

Если в ответе отсутствует код, который вы ожидали увидеть по каталогу, об этом стоит сообщить, а не обходить проблему - отсутствующий код это реальный пробел, и он усложняет жизнь следующему, кто с этим столкнётся.

## Пустой ответ - это не успех

Проверка через провайдера, вернувшая пустое тело, - это не то же самое, что чистый результат. Обрабатывайте "нет данных" как отдельный случай в вашем коде, а не приравнивайте его к успеху - особенно для проверки по базам данных и скрининга кошельков, где неподключённый сервис и настоящее отсутствие совпадения могут выглядеть одинаково со стороны.

## Тестирование путей ошибок

Sandbox детерминированно вызывает конкретные сбои, и это единственный разумный способ протестировать обработку ошибок. См. [тестирование в sandbox](https://help.didit.me/ru/getting-started/sandbox-and-testing).