Waafir
Эта страница переведена машинным способом и ожидает проверки человеком. Возможны неточности.

Ошибки и коды состояния

Эта страница — сводный справочник по конвертам ответов, которые используют все маршруты кредитного 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" }
  ]
}
ПолеТипПримечания
errorstringКраткое понятное человеку описание.
fieldErrors[].pathstringПуть к проблемному полю через точку. (root) обозначает само тело, например когда не удался разбор JSON.
fieldErrors[].messagestringПонятное человеку объяснение.

Некоторые маршруты при ошибках в параметрах запроса возвращают 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" }
  ]
}
ПолеТипПримечания
errorstringПонятное человеку описание.
codestringСтабильный машиночитаемый код; см. глоссарий.
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_CONFLICT409POST /borrowers, POST /loans, POST /payments.Действующая строка с тем же id уже существует.
PORTFOLIO_NOT_FOUND404Все маршруты записи для отдельных записей.portfolioId в теле не существует в вашей организации.
REFERENCED_ENTITY_NOT_FOUND422POST /loans, POST /payments.borrowerId или loanId ссылается на строку, которая не существует как действующая в том же портфеле.
INVALID_STATUS_TRANSITION422PATCH /loans/{loanRef}/status.Пары исходного и целевого статусов нет в матрице переходов.
IDEMPOTENCY_CONFLICT409PATCH /loans/{loanRef}/status.Idempotency-Key уже использован для другого перехода статуса. Отправьте новый переход с новым ключом.
IDEMPOTENCY_KEY_REUSED409POST /imports.Idempotency-Key уже использован для импорта с другими параметрами запроса (kind, filename, sizeBytes, …). Ответ содержит importId и mismatchedFields. Отправьте новый импорт с новым ключом.
MONITORING_INVESTOR_FORBIDDEN403Все маршруты мониторинга займов, включая пакетную загрузку NDJSON.Вызывающий — учётная запись инвестора; инвесторы не могут использовать API данных мониторинга.
CHECK_VIOLATION400POST /payments.Нарушено правило данных (обычно инвариант прощения долга; уровень схемы отклоняет такой же формат ещё при проверке).
NOT_FOUND404GET /borrowers/{id}, GET /payments/{id}, PATCH /loans/.../status, POST /payments/{id}/cancel, GET /loans/{externalId}.Искомая строка не существует как действующая в указанной области или принадлежит другой организации.
UNKNOWN_KIND400POST /imports.kind не является одним из шести кредитных видов. Ответ содержит массив allowed.
COMMIT_FAILED409POST /imports/{id}/commit.Платформа не нашла загруженный файл; обычно загрузка не завершилась. Повторите загрузку, затем подтвердите снова.

Пространство кодов пакетной загрузки NDJSON

КодСтатусУсловие
batch_too_large413Тело превышает 10 000 строк или 10 MB. error и fieldErrors[].message различают ограничение по строкам и по байтам.
portfolio_id_required400?portfolioId=<UUID> отсутствует или не является корректным UUID.
portfolio_not_found404?portfolioId= не существует как действующий портфель в вашей организации.
invalid_body400Тело запроса не удалось прочитать как текст.
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_mismatchportfolioId строки не совпадает с портфелем-привязкой импорта.
processor_errorНепредвиденный сбой обработчика при обработке этой строки.

Ошибки при сохранении строки (отсутствующая ссылка, дубликат, нарушенное правило данных) отображаются под одним из указанных выше кодов с подробностями в errorMessage.

Ошибки по строкам никогда не поднимаются до ответа верхнего уровня с кодом, отличным от 200, в пакетной загрузке — пакет в целом успешен, если сам запрос был корректным; коды для строк сообщают, что именно сохранилось.

Семантика повторов

Безопасный для повторов шаблон для любого изменяющего маршрута:

  1. Генерируйте детерминированный Idempotency-Key для каждой логической операции. Подойдёт UUIDv4 плюс признак маршрута.
  2. Отправьте запрос с этим ключом.
  3. При любом из 2xx, 409 ID_CONFLICT, 409 IDEMPOTENCY_CONFLICT, 409 IDEMPOTENCY_KEY_REUSED, 404, 403, 400, 413 или 422 — не повторяйте. Результат окончательный.
  4. При 429 — повторите через время, указанное в заголовке Retry-After.
  5. При 500 или сетевой ошибке — повторите небольшое фиксированное число раз с экспоненциальной задержкой. Idempotency-Key делает повтор безопасным независимо от того, дошла ли первая попытка.

Повтор успешного запроса с тем же Idempotency-Key возвращает тот же ответ, что и исходный, с reused: true для затронутой сущности. Это канонический способ восстановления после сетевого сбоя.

Чего платформа никогда не возвращает

Для операционной отладки полезно знать и обратную сторону:

  • Никакой код состояния 5xx не считается платформой штатным поведением. 500 — всегда ошибка, которую нужно исправить; никогда не пишите клиентскую логику, зависящую от конкретной структуры ответа 500.
  • Никакой ответ 404 не раскрывает принадлежность арендатору. 404 для строки, существующей в другой организации, выглядит так же, как 404 для строки, которой нет нигде. Не пишите клиентскую логику, которая делает выводы о существовании данных других клиентов.
  • Никакой успешный ответ не содержит в теле поле success: false. Первоисточником успешности вызова служит код состояния; тело содержит подробности.
  • Никакой маршрут записи не возвращает свой UUID в стиле параметра пути (заголовок "Location"). Созданный UUID возвращается в поле id тела ответа.