Не повторять сразу
400/401/403/422 обычно требуют исправления данных, ключа или прав.
Ошибки
Ошибки API и что с ними делать
Все ошибки возвращаются в едином JSON-формате. В интерфейсе партнёра лучше показывать не технический код, а понятное действие: исправить данные, пополнить баланс, повторить позже или обратиться к администратору.
400invalid_check_input401invalid_api_key / revoked_api_key / expired_api_key402insufficient_funds403scope_denied404check_not_found / valuation_not_found / document_job_not_found / generation_not_found / monitor_not_found
Формат ошибки
request_id всегда сохраняйте в логах: по нему поддержка RealIQ быстрее найдёт конкретный вызов.
{
"error_code": "insufficient_funds",
"message": "На балансе агентства недостаточно средств.",
"request_id": "req_1780000000_abcd"
}Таблица кодов ошибок
Основные действия приведены ниже. Полный реестр находится в OpenAPI: x-error-codes.http для ошибок запроса и x-error-codes.result для error.code внутри результата задачи. Поле error.retryable описывает повтор задачи, а не повтор GET. Для неизвестного кода сохраняйте request_id и показывайте безопасное общее сообщение.
| HTTP | error_code | Причина | Что показать пользователю | Повторять? |
|---|---|---|---|---|
| 400 | invalid_check_input | Некорректные или неполные данные проверки. | Попросить исправить данные. | Нет, сначала исправить состав запроса. |
| 401 | invalid_api_key / revoked_api_key / expired_api_key | API-ключ не передан или неверен. | Сообщить администратору интеграции. | Нет, пока не исправлен ключ. |
| 402 | insufficient_funds | Недостаточно баланса для боевого запуска. | Показать пополнение баланса. | Да, после пополнения. |
| 403 | scope_denied | У ключа нет права на метод. | Попросить выдать нужное право. | Нет, пока не изменены права. |
| 404 | check_not_found / valuation_not_found / document_job_not_found / generation_not_found / monitor_not_found | Объект не найден или принадлежит другому аккаунту. | Проверить ID и API-ключ. | Нет, если ID неверный. |
| 409 | idempotency_conflict | Idempotency-Key повторён с другим телом. | Создать новый ключ идемпотентности. | Да, с новым Idempotency-Key. |
| 413 | document_too_large | Файл документа превышает лимит. | Сжать файл или разделить комплект. | Да, после изменения файла. |
| 422 | validation_error | Формат запроса не прошёл валидацию. | Показать ошибки полей в интерфейсе. | Нет, пока не исправлен payload. |
| 429 | parallel_limit_exceeded | Достигнут лимит исполняемых задач. | Дождаться завершения задач. | Да, после Retry-After с прежним ключом идемпотентности. |
| 429 | rate_limited | Превышен лимит запросов. | Показать ожидание и Retry-After. | Да, после указанной задержки. |
| 500 | internal_error | Внутренняя ошибка API. | Сохранить request_id и повторить позже. | Да, с увеличением задержки. |
| 503 | rate_limit_unavailable | Проверка лимита временно недоступна. | Сохранить request_id. | Да, с прежним Idempotency-Key после Retry-After. |
Правило повторов
Повторять с задержкой
429/500/503 можно повторять с задержкой и ограничением числа попыток.
Не создавать дубли
Для live создания checks, bulk, valuation, document-check, document-generator и monitors обязателен прежний Idempotency-Key при повторе. Новый ключ означает новую операцию.