> For the complete documentation index, see [llms.txt](https://docs.metasleuth.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.metasleuth.io/ru/blocksec-aml-api/introduction/response-format.md).

# Формат ответа

Рабочий API-запрос успешен только при HTTP-статусе **200** и верхнеуровневом JSON `code`, равном **200000**. Проверяйте оба значения; одного HTTP 200 недостаточно.

## Поля ответа

| Поле         | Описание                                                                                                               |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `request_id` | Идентификатор запроса, если доступен. Укажите его при обращении в поддержку. Может быть пустым.                        |
| `code`       | Целочисленный бизнес-код состояния. `200000` означает успех. Он отличается от кодов меток адресов и индикаторов риска. |
| `message`    | Описание результата. Обрабатывайте ошибки по бизнес-коду, а не по совпадению текста сообщения.                         |
| `data`       | Данные результата для конкретного эндпоинта. В ошибках поле может отсутствовать.                                       |
| `cause`      | Необязательные дополнительные сведения об ошибке в ответе Address Label API.                                           |

Например, недействительная подпись возвращает HTTP 401:

```json
{
  "request_id": "example-request-id",
  "code": 401002,
  "message": "Invalid request signature"
}
```

Не все ошибки возвращают JSON или бизнес-код. Обрабатывайте также пустые ответы и ответы не в JSON.

## Ошибки аутентификации и безопасности

Следующие коды применяются к зарегистрированным рабочим эндпоинтам Address Label API и Risk Score API.

| Код      | HTTP | Сообщение                                                               | Рекомендуемое действие                                                                                                                                                                                  |
| -------- | ---- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403001` | 403  | API security setup is required. Enable IP allowlist or request signing. | Откройте API Security Settings и завершите обязательную настройку, показанную на странице управления API.                                                                                               |
| `403002` | 403  | Request IP is not allowed                                               | Проверьте публичный исходящий IP приложения и настроенный IP Allowlist.                                                                                                                                 |
| `401001` | 401  | Request signing is not configured                                       | Настройте Request Signing и убедитесь, что для сервиса доступен секрет.                                                                                                                                 |
| `401002` | 401  | Invalid request signature                                               | Проверьте все заголовки подписи, секрет, метод, полный путь, нормализованный запрос и точные байты тела. Неполные заголовки, неверная длина подписи или nonce более 256 байт также вызывают эту ошибку. |
| `401003` | 401  | Invalid request timestamp                                               | Используйте метку времени Unix в секундах. Синхронизируйте часы; отклонение от сервера не должно превышать 5 минут.                                                                                     |
| `401004` | 401  | Request has already been used                                           | Перед повтором создайте новый nonce и пересчитайте подпись.                                                                                                                                             |
| `413001` | 413  | Request body is too large                                               | Ограничьте тело 16 MiB и проверьте, не была ли загрузка прервана или завершена не полностью.                                                                                                            |

Если включены IP Allowlist и Request Signing, запрос должен пройти обе проверки. Любой непустой заголовок подписи запускает её проверку даже при отключённом Request Signing. Ответ сообщает о первой неудачной проверке безопасности.

Запросы, отклонённые проверкой безопасности, не передаются в рабочую обработку и не оплачиваются.

## Ошибки сервиса

| Код      | HTTP | Сообщение                                   | Рекомендуемое действие                                                                                                          |
| -------- | ---- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `500001` | 500  | API security policy is unavailable          | Повторите с ограниченной экспоненциальной задержкой. Если проблема сохраняется, обратитесь в поддержку.                         |
| `500002` | 500  | API subscription information is unavailable | Повторите с ограниченной экспоненциальной задержкой. Если проблема сохраняется, обратитесь в поддержку.                         |
| `500003` | 500  | Request signing verification is unavailable | Повторите с ограниченной экспоненциальной задержкой, новым nonce и подписью. Если проблема сохраняется, обратитесь в поддержку. |
| `502001` | 502  | Invalid upstream response                   | Передайте в поддержку сведения о запросе и его идентификатор, если доступен.                                                    |
| `502002` | 502  | Failed to receive upstream response         | Повторите с ограниченной экспоненциальной задержкой. Если проблема сохраняется, обратитесь в поддержку.                         |

## Существующие бизнес-коды

Существующие коды по-прежнему поддерживаются. Текст зависит от сервиса и версии; определяйте ошибку по `code`.

| Код      | Описание                                                                             | Рекомендуемое действие                                                                                                        |
| -------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `200000` | Success                                                                              | Прочитайте `data` соответствующего эндпоинта.                                                                                 |
| `400001` | Unauthorized operation                                                               | Проверьте права доступа. Этот код отличается от кодов безопасности выше.                                                      |
| `400002` | Request rate is too high. Please try again later.                                    | Снизьте частоту запросов и используйте задержку. Ограничение частоты возвращает HTTP 429.                                     |
| `400004` | Invalid params                                                                       | Проверьте схему запроса эндпоинта.                                                                                            |
| `400005` | User does not exist                                                                  | Устаревший код, сохранённый для совместимости.                                                                                |
| `400006` | Server busy                                                                          | Повторите с ограниченной экспоненциальной задержкой.                                                                          |
| `400007` | Invalid API key                                                                      | Проверьте ключ, сервис и срок действия. Сообщение может быть `Invalid api-key`.                                               |
| `400008` | Invalid auth format                                                                  | Устаревший код для совместимости; проверьте заголовки аутентификации.                                                         |
| `400009` | The API key is expired                                                               | Проверьте доступ к API и получите действительные учётные данные.                                                              |
| `400010` | Route not found                                                                      | Проверьте базовый URL и путь. Сообщение может быть `Router not found!` или `404 not found!`.                                  |
| `400011` | Invalid address. Please ensure that you have provided the correct chain and address. | Проверьте адрес и его цепь.                                                                                                   |
| `400012` | Daily request limit exceeded. Please try again tomorrow.                             | Проверьте оставшуюся квоту и время сброса. Ограничение квоты возвращает HTTP 429.                                             |
| `400013` | Unsupported chain                                                                    | Проверьте `chain_id`. Текущее сообщение: `Invalid params. Unsupported chain id`; старая документация упоминает название цепи. |
| `400014` | Method not allowed                                                                   | Проверьте HTTP-метод. Возможен HTTP 405 без бизнес-кода.                                                                      |
| `400015` | The number of addresses in a single request exceeds the limit.                       | Уменьшите пакет. Для запросов меток в нескольких цепях лимит учитывает число адресов, умноженное на число цепей.              |
| `500000` | Internal error                                                                       | Повторите с ограниченной экспоненциальной задержкой. Если проблема сохраняется, обратитесь в поддержку.                       |

## Ограничения частоты и квота

Ограничения возвращают HTTP **429**: `400002` для частоты запросов, `400012` для недостаточной суточной квоты. Если квоты не хватает на весь пакет, рабочие данные не возвращаются и частичное списание не производится.

При наличии следующие заголовки описывают суточную квоту:

| Заголовок               | Значение                                                               |
| ----------------------- | ---------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | Суточный лимит квоты.                                                  |
| `X-RateLimit-Used`      | Использованная квота.                                                  |
| `X-RateLimit-Remaining` | Оставшаяся квота.                                                      |
| `X-RateLimit-Reset`     | Следующий сброс: ближайшая полночь UTC, метка времени Unix в секундах. |
| `X-RateLimit-Cost`      | Квота, списанная за этот ответ.                                        |

Отказы аутентификации не содержат заголовков квоты. Сейчас сервис не возвращает `Retry-After`. Списки поддерживаемых цепей и индикаторов риска требуют аутентификации, применимых проверок безопасности и соблюдения частоты даже без расхода квоты.

## Безопасные повторы

* Для каждого подписанного повтора создавайте новые метку времени, nonce и подпись.
* Nonce предотвращает воспроизведение; это не ключ идемпотентности. Успешный повтор может оплачиваться снова.
* Не повторяйте запросы с неверными учётными данными, подписями, запрещёнными IP или параметрами, не исправив причину.
* При временных ошибках используйте ограниченную экспоненциальную задержку. Если ответ потерян или результат неизвестен, не считайте исходный запрос необработанным или неоплаченным.

## Ошибки без бизнес-кода

Некоторые ошибки содержат лишь HTTP-статус и пустое тело либо тело не в JSON.

| HTTP | Возможная причина                                       | Рекомендуемое действие                                                     |
| ---- | ------------------------------------------------------- | -------------------------------------------------------------------------- |
| 404  | Неизвестный эндпоинт.                                   | Проверьте базовый URL и путь.                                              |
| 405  | Неподдерживаемый метод.                                 | Проверьте метод и заголовок `Allow`, если он есть.                         |
| 413  | Запрос отклонён до проверки подписи из-за размера тела. | Уменьшите размер тела запроса.                                             |
| 500  | Непредвиденная ошибка сервера.                          | Ограничьте число повторов; при сохранении проблемы обратитесь в поддержку. |
| 502  | Ошибка связи с внутренним сервисом API.                 | Ограничьте число повторов; при сохранении проблемы обратитесь в поддержку. |
| 503  | Тайм-аут или временная недоступность сервиса.           | Повторите с ограниченной экспоненциальной задержкой.                       |

При обращении в [поддержку](mailto:ms_support@blocksec.com) укажите эндпоинт, HTTP-метод, время UTC, HTTP-статус, бизнес-код и идентификатор запроса, если он доступен. Не отправляйте API-ключ, секрет, подпись и заголовки авторизации. Передавайте только путь без чувствительных значений параметров; маскируйте учётные данные, персональные данные и чувствительные данные запросов/ответов в журналах, снимках экрана и вложениях.
