Ошибки и коды состояния
Эта страница — сводный справочник по конвертам ответов, которые используют все маршруты кредитного API. В документации по каждому маршруту перечислены коды состояния, которые возвращает конкретный маршрут; здесь описана структура каждого конверта и каталог именованных значений code, которые вы можете получить.
Прочитайте её один раз перед интеграцией и возвращайтесь к ней всякий раз, когда статус, отличный от 2xx, окажется неожиданным.
Каталог кодов состояния
| Статус | Когда вы его видите | Пример маршрута |
|---|---|---|
200 OK | Успешное чтение, идемпотентный повтор, мягкая отмена, обработанный пакет, переход статуса. | Все маршруты, кроме создания. |
201 Created | Успешное первичное создание на маршруте для отдельной записи. | POST /borrowers. |
202 Accepted | Асинхронный импорт запущен — работа продолжается в фоне. | POST /imports. |
204 No Content | Сейчас не возвращается ни одним кредитным маршрутом. | — |
400 Bad Request | Ошибка проверки запроса: некорректный JSON, некорректные параметры запроса, нарушение схемы. | Все изменяющие маршруты. |
401 Unauthorized | Нет заголовка Authorization, неизвестный или отозванный токен. | Все маршруты. |
403 Forbidden | Вызывающий — учётная запись инвестора; инвесторы не могут использовать API данных мониторинга (MONITORING_INVESTOR_FORBIDDEN). ?unmask=true без прав администратора не возвращает 403: возвращается 200 с маскированными PII. | Все маршруты. |
404 Not Found | Ресурс не существует или принадлежит другой организации. | Все маршруты, обращающиеся к ресурсу. |
409 Conflict | Действующая строка с этим id уже существует, Idempotency-Key повторно использован для другого перехода статуса или на этапе подтверждения не удалось найти загруженный файл. | POST /borrowers, PATCH /loans/.../status, POST /imports/{id}/commit. |
413 Payload Too Large | Пакет NDJSON превышает ограничение по числу строк или байтов. | POST /bulk/{entity}. |
422 Unprocessable Entity | Строка, на которую указывает ссылка, не существует как действующая в том же портфеле (REFERENCED_ENTITY_NOT_FOUND), или запрошенного перехода статуса нет в матрице переходов (INVALID_STATUS_TRANSITION). Ошибки проверки используют 400. | POST /loans, POST /payments, PATCH /loans/{loanRef}/status. |
429 Too Many Requests | Превышено ограничение частоты запросов. Платформа применяет ограничения для каждой организации; заголовок ответа Retry-After указывает число секунд. | Все маршруты. |
500 Internal Server Error | Необработанная ошибка платформы. Считайте её временной; повтор с тем же Idempotency-Key безопасен. | Все маршруты. |
Любой 4xx, кроме 429, считайте дефектом запроса — логика клиента должна отклонять такие входные данные, а не повторять запрос. 429 и 500 считайте временными и повторяйте с экспоненциальной задержкой; Idempotency-Key делает повтор безопасным.
Стандартные конверты
Кредитный API использует три конверта ответа для неуспешных кодов состояния. Структура конверта показывает, с каким видом сбоя вы имеете дело.
Конверт проверки — 400 Bad Request
Используется для нарушений схемы, некорректных параметров запроса и некорректных путей.
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}| Поле | Тип | Примечания |
|---|---|---|
error | string | Краткое понятное человеку описание. |
fieldErrors[].path | string | Путь к проблемному полю через точку. (root) обозначает само тело, например когда не удался разбор JSON. |
fieldErrors[].message | string | Понятное человеку объяснение. |
Некоторые маршруты при ошибках в параметрах запроса возвращают errors[] вместо fieldErrors[] (соглашение фреймворка различается между интерфейсами). Структура path/message идентична; при разборе считайте эти два имени массива взаимозаменяемыми.
Конверт с именованным кодом — 4xx
Используется, когда у сбоя есть конкретная причина, которую платформа обозначает стабильным значением code. Наличие fieldErrors необязательно и зависит от того, можно ли отнести сбой к конкретному полю.
{
"error": "a borrower with this id already exists",
"code": "ID_CONFLICT",
"fieldErrors": [
{ "path": "id", "message": "a borrower with this id already exists" }
]
}| Поле | Тип | Примечания |
|---|---|---|
error | string | Понятное человеку описание. |
code | string | Стабильный машиночитаемый код; см. глоссарий. |
fieldErrors[] | array | absent | Присутствует, когда сбой указывает на конкретное поле. |
Некоторые конверты содержат дополнительный структурированный контекст — например, batch_too_large включает блок fieldErrors с указанием превышенного ограничения. Такие случаи названы в документации по маршрутам.
Конверт с одной ошибкой — 404 / 401
Используется для лаконичных ответов, когда дополнительный контекст вызывающей стороне не поможет. Типичный пример — 404:
{ "error": "Not found" }Некоторые маршруты возвращают { "error": "...", "code": "NOT_FOUND" }; наличие или отсутствие code в ответе 404 считайте информативным, но не существенным.
Два пространства кодов: верхний и нижний регистр
Кредитный API использует два отдельных пространства имён code, намеренно разделённых по способу загрузки:
- Маршруты для отдельных записей (POST, PATCH, отмена и GET для сверки) возвращают значения кода в
UPPER_CASE:ID_CONFLICT,PORTFOLIO_NOT_FOUND,REFERENCED_ENTITY_NOT_FOUND,INVALID_STATUS_TRANSITION,CHECK_VIOLATION,NOT_FOUND,UNKNOWN_KIND,COMMIT_FAILED,IDEMPOTENCY_CONFLICT,IDEMPOTENCY_KEY_REUSED,MONITORING_INVESTOR_FORBIDDEN. Маршруты пакетной загрузки NDJSON тоже возвращаютMONITORING_INVESTOR_FORBIDDENв верхнем регистре. - Маршруты пакетной загрузки NDJSON возвращают значения кода в
lower_case:batch_too_large,portfolio_not_found,portfolio_id_required,invalid_body,invalid_json, а также коды для строк, описанные ниже.
Ветвясь по code в клиенте, сравнивайте с точным учётом регистра. Каждое из двух пространств кодов стабильно само по себе; не нормализуйте их.
Глоссарий кодов ошибок
Платформа присваивает стабильный code каждому именованному сценарию сбоя. Используйте их для программного ветвления; текст сообщения error может меняться.
Пространство кодов для отдельных записей
| Код | Статус | Возвращается | Условие |
|---|---|---|---|
ID_CONFLICT | 409 | POST /borrowers, POST /loans, POST /payments. | Действующая строка с тем же id уже существует. |
PORTFOLIO_NOT_FOUND | 404 | Все маршруты записи для отдельных записей. | portfolioId в теле не существует в вашей организации. |
REFERENCED_ENTITY_NOT_FOUND | 422 | POST /loans, POST /payments. | borrowerId или loanId ссылается на строку, которая не существует как действующая в том же портфеле. |
INVALID_STATUS_TRANSITION | 422 | PATCH /loans/{loanRef}/status. | Пары исходного и целевого статусов нет в матрице переходов. |
IDEMPOTENCY_CONFLICT | 409 | PATCH /loans/{loanRef}/status. | Idempotency-Key уже использован для другого перехода статуса. Отправьте новый переход с новым ключом. |
IDEMPOTENCY_KEY_REUSED | 409 | POST /imports. | Idempotency-Key уже использован для импорта с другими параметрами запроса (kind, filename, sizeBytes, …). Ответ содержит importId и mismatchedFields. Отправьте новый импорт с новым ключом. |
MONITORING_INVESTOR_FORBIDDEN | 403 | Все маршруты мониторинга займов, включая пакетную загрузку NDJSON. | Вызывающий — учётная запись инвестора; инвесторы не могут использовать API данных мониторинга. |
CHECK_VIOLATION | 400 | POST /payments. | Нарушено правило данных (обычно инвариант прощения долга; уровень схемы отклоняет такой же формат ещё при проверке). |
NOT_FOUND | 404 | GET /borrowers/{id}, GET /payments/{id}, PATCH /loans/.../status, POST /payments/{id}/cancel, GET /loans/{externalId}. | Искомая строка не существует как действующая в указанной области или принадлежит другой организации. |
UNKNOWN_KIND | 400 | POST /imports. | kind не является одним из шести кредитных видов. Ответ содержит массив allowed. |
COMMIT_FAILED | 409 | POST /imports/{id}/commit. | Платформа не нашла загруженный файл; обычно загрузка не завершилась. Повторите загрузку, затем подтвердите снова. |
Пространство кодов пакетной загрузки NDJSON
| Код | Статус | Условие |
|---|---|---|
batch_too_large | 413 | Тело превышает 10 000 строк или 10 MB. error и fieldErrors[].message различают ограничение по строкам и по байтам. |
portfolio_id_required | 400 | ?portfolioId=<UUID> отсутствует или не является корректным UUID. |
portfolio_not_found | 404 | ?portfolioId= не существует как действующий портфель в вашей организации. |
invalid_body | 400 | Тело запроса не удалось прочитать как текст. |
invalid_json | (для строки) | Строка не является корректным JSON. Отображается внутри массива errors[] по строкам; пакет возвращает 200. |
Код, которого нет в этом глоссарии, означает, что платформа добавила новый именованный код после последней редакции страницы. Всегда записывайте значение code в журнал дословно вместе с ошибкой вашего приложения, чтобы инженерная команда могла сопоставить события.
Коды ошибок для строк (пакетная загрузка и асинхронный импорт)
И пакетная загрузка NDJSON, и асинхронный импорт возвращают ошибки по строкам. Пакетная загрузка использует один набор значений; асинхронный импорт — похожий, но немного отличающийся (в частности, в нём validation_error вместо validation_failed, что отражает более старый интерфейс). Записи для строк описывают сбои отдельных строк внутри успешного пакета, а не сбои конверта.
Коды для строк в пакетной загрузке NDJSON
| Код для строки | Условие |
|---|---|
validation_failed | Строка не прошла проверку по схеме. Поле message содержит ошибки проверки. |
fk_violation | Ссылка по внешнему ключу в строке (например, borrowerId, loanId) не указывает на действующую строку в том же портфеле. |
unique_violation | Действующая строка с тем же (portfolio, externalId) или id уже существует. (Отдельного кода id_conflict для строки нет; обе разновидности конфликта идентификаторов вызывающей стороны отображаются здесь.) |
check_violation | Нарушено правило данных — обычно правило прощения долга для платежа. |
db_error | Непредвиденная ошибка при сохранении этой строки. Строка помечается как неудачная; обработка пакета продолжается. |
invalid_json | Строка не является корректным JSON. Платформа обрабатывает остальную часть пакета. |
Коды для строк в асинхронном импорте
| Код для строки | Условие |
|---|---|
parse_error | Строка не является корректным JSON. |
validation_error | Строка не прошла проверку по схеме. |
portfolio_mismatch | portfolioId строки не совпадает с портфелем-привязкой импорта. |
processor_error | Непредвиденный сбой обработчика при обработке этой строки. |
Ошибки при сохранении строки (отсутствующая ссылка, дубликат, нарушенное правило данных) отображаются под одним из указанных выше кодов с подробностями в errorMessage.
Ошибки по строкам никогда не поднимаются до ответа верхнего уровня с кодом, отличным от 200, в пакетной загрузке — пакет в целом успешен, если сам запрос был корректным; коды для строк сообщают, что именно сохранилось.
Семантика повторов
Безопасный для повторов шаблон для любого изменяющего маршрута:
- Генерируйте детерминированный
Idempotency-Keyдля каждой логической операции. Подойдёт UUIDv4 плюс признак маршрута. - Отправьте запрос с этим ключом.
- При любом из
2xx,409 ID_CONFLICT,409 IDEMPOTENCY_CONFLICT,409 IDEMPOTENCY_KEY_REUSED,404,403,400,413или422— не повторяйте. Результат окончательный. - При
429— повторите через время, указанное в заголовкеRetry-After. - При
500или сетевой ошибке — повторите небольшое фиксированное число раз с экспоненциальной задержкой.Idempotency-Keyделает повтор безопасным независимо от того, дошла ли первая попытка.
Повтор успешного запроса с тем же Idempotency-Key возвращает тот же ответ, что и исходный, с reused: true для затронутой сущности. Это канонический способ восстановления после сетевого сбоя.
Чего платформа никогда не возвращает
Для операционной отладки полезно знать и обратную сторону:
- Никакой код состояния
5xxне считается платформой штатным поведением.500— всегда ошибка, которую нужно исправить; никогда не пишите клиентскую логику, зависящую от конкретной структуры ответа500. - Никакой ответ
404не раскрывает принадлежность арендатору.404для строки, существующей в другой организации, выглядит так же, как404для строки, которой нет нигде. Не пишите клиентскую логику, которая делает выводы о существовании данных других клиентов. - Никакой успешный ответ не содержит в теле поле
success: false. Первоисточником успешности вызова служит код состояния; тело содержит подробности. - Никакой маршрут записи не возвращает свой UUID в стиле параметра пути (заголовок "Location"). Созданный UUID возвращается в поле
idтела ответа.