Коды ошибок

Ошибки AML API возвращаются в едином конверте с машинным code, человекочитаемым message и идентификатором запроса request_id для обращения в поддержку.

Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The address field is required.",
    "request_id": "req_9f3a1c7e"
  }
}

⚠

Две формы ошибок — учтите при разборе

Ошибки бизнес-логики (валидация, «не найдено», лимиты) приходят во вложенном конверте error.code (пример выше). Но гейт доступа — аутентификация (401) и B2B-доступ (403) — отвечает в плоской форме с полем error_code на верхнем уровне. Разбирайте обе: проверяйте и верхнеуровневый error_code, и вложенный error.code.

Responses

{
  "message": "B2B access is not enabled for this account. Contact admin@fin-os.io to request B2B integration onboarding.",
  "error_code": "B2B_ACCESS_REQUIRED",
  "docs": "https://fin-os.io/docs/b2b"
}

Справочник кодов

Name	Type	Required	Description
`UNAUTHENTICATED`	`401`	optional	Отсутствует или недействителен ключ `Bearer sk_(live\|test)_...`.
`B2B_ACCESS_REQUIRED`	`403`	optional	Ключ валиден, но доступ к API не активирован (нет `b2b_enabled` или отключён сервис `aml`). Подключение — admin@fin-os.io.
`NOT_FOUND`	`404`	optional	Проверка с таким `id` не найдена в вашем контуре и текущем окружении.
`VALIDATION_ERROR`	`422`	optional	`address` не задан или длиннее 120 символов, либо `network` длиннее 20 символов.
`NETWORK_UNRESOLVED`	`422`	optional	В live не удалось определить сеть по формату адреса — передайте `network` явно.
`RATE_LIMITED`	`429`	optional	Слишком много запросов (в т.ч. при перегрузке вышестоящих источников). Реализуйте экспоненциальный backoff и повтор.

ℹ

Доступ и провижининг

403 B2B_ACCESS_REQUIRED означает, что ключ рабочий, но сервис ещё не включён администратором. Это разовое действие на нашей стороне после подключения — не ошибка интеграции. Начните с sandbox (sk_test_): он доступен сразу после выдачи ключей и возвращает детерминированные синтетические отчёты.

⚠

Частичные данные ≠ «чисто»

Если часть источников временно недоступна, проверка всё равно возвращается — с тем скорингом, что удалось собрать. Поэтому низкий risk_score может означать и «чисто», и «часть источников не ответила». Для критичных операций трактуйте отсутствие сигналов консервативно и при необходимости перепроверяйте позже по тому же адресу.