# Коды ошибок

> Каталог из 36 кодов ошибок API LegalStack (RFC 9457)

Все ошибки API возвращаются в формате `application/problem+json` (RFC 9457).
Поле `code` — стабильный машинный код из таблицы ниже, поле `type` — ссылка вида `https://legalstack.ru/errors/<код-в-kebab-case>` на его описание. Поле `title` — краткое описание, соответствующее HTTP-статусу, `detail` — пояснение к конкретному случаю, `request_id` — идентификатор запроса для обращения в поддержку.

| Код | HTTP-статус | Что означает | Что делать |
| --- | --- | --- | --- |
| `IDEMPOTENCY_KEY_REQUIRED` <a id="idempotency-key-required" /> | 400 | Операция требует заголовок `Idempotency-Key`. | Передайте уникальный ключ в заголовке `Idempotency-Key`. |
| `IDEMPOTENCY_KEY_INVALID` <a id="idempotency-key-invalid" /> | 400 | Значение `Idempotency-Key` не соответствует формату. | Используйте от 8 до 255 символов из набора `A-Z`, `a-z`, `0-9` и `_ . : + / = -`. |
| `VALIDATION_FAILED` <a id="validation-failed" /> | 400 | Параметры или тело запроса не прошли проверку. | Исправьте поля из массива `errors`: `pointer` указывает на поле, `reason` — на причину. |
| `BAD_REQUEST` <a id="bad-request" /> | 400 | Запрос сформирован некорректно. | Проверьте формат запроса; пояснение — в поле `detail`. |
| `NO_TOKEN` <a id="no-token" /> | 401 | Запрос отправлен без токена доступа. | Передайте токен в заголовке `Authorization: DPoP <токен>` вместе с заголовком `DPoP`, см. гайд «Аутентификация». |
| `INVALID_TOKEN` <a id="invalid-token" /> | 401 | Токен недействителен: повреждён, подписан неизвестным ключом, отозван, не привязан к клиенту или вместо токена передан персональный ключ. | Получите новый токен; персональный ключ предварительно обменяйте на токен в `POST /oauth/token`. |
| `TOKEN_EXPIRED` <a id="token-expired" /> | 401 | Срок действия токена истёк. | Обновите токен с помощью refresh-токена или получите новый. |
| `TOKEN_MISSING_TEAM` <a id="token-missing-team" /> | 401 | Токен выдан без привязки к команде. | Выберите команду и получите токен заново. |
| `OAUTH_MISSING_TOKEN` <a id="oauth-missing-token" /> | 401 | Запрос отправлен без OAuth-токена доступа. | Передайте access token в заголовке `Authorization`. |
| `OAUTH_INVALID_SCHEME` <a id="oauth-invalid-scheme" /> | 401 | В заголовке `Authorization` указана неподдерживаемая схема. | Используйте схему `DPoP` для токена с привязкой к ключу и `Bearer` для токена с привязкой к mTLS-сертификату. |
| `OAUTH_INVALID_TOKEN` <a id="oauth-invalid-token" /> | 401 | OAuth-токен недействителен или отозван. | Получите новый токен. |
| `OAUTH_DPOP_REQUIRED` <a id="oauth-dpop-required" /> | 401 | Токен привязан к ключу DPoP, но запрос отправлен без DPoP-доказательства. | Передайте заголовок `DPoP` с доказательством, сформированным для этого запроса. |
| `OAUTH_DPOP_SCHEME_MISMATCH` <a id="oauth-dpop-scheme-mismatch" /> | 401 | Схема авторизации не соответствует типу токена. | Передавайте токены с привязкой к ключу со схемой `DPoP`, токены с привязкой к сертификату — со схемой `Bearer`. |
| `OAUTH_INVALID_DPOP_PROOF` <a id="oauth-invalid-dpop-proof" /> | 401 | DPoP-доказательство не прошло проверку: подпись, метод, адрес, время или повторное использование. | Сформируйте новое доказательство для этого запроса; если сервер вернул заголовок `DPoP-Nonce`, включите его значение. |
| `USE_DPOP_NONCE` <a id="use-dpop-nonce" /> | 401 | DPoP-доказательство отправлено без актуального серверного nonce или с устаревшим. | Возьмите значение заголовка `DPoP-Nonce` из этого ответа, включите его в поле `nonce` нового доказательства и повторите запрос. |
| `INSUFFICIENT_ROLE` <a id="insufficient-role" /> | 403 | Роли пользователя в команде недостаточно для операции. | Попросите владельца или администратора команды выдать нужную роль. |
| `INSUFFICIENT_SCOPE` <a id="insufficient-scope" /> | 403 | Токену не выдан scope, который требует операция. | Запросите токен с нужным scope — он указан у операции в справочнике API. |
| `TENANT_MISMATCH` <a id="tenant-mismatch" /> | 403 | Ресурс принадлежит другой команде. | Проверьте идентификатор ресурса или получите токен нужной команды. |
| `EMAIL_NOT_VERIFIED` <a id="email-not-verified" /> | 403 | E-mail пользователя не подтверждён. | Подтвердите e-mail по ссылке из письма. |
| `OAUTH_INSUFFICIENT_SCOPE` <a id="oauth-insufficient-scope" /> | 403 | OAuth-токену не выдан scope, который требует операция. | Запросите токен с нужным scope — он указан у операции в справочнике API. |
| `PERMISSION_DENIED` <a id="permission-denied" /> | 403 | Нет прав на этот ресурс. | Попросите доступ у владельца ресурса или администратора команды. |
| `NOT_FOUND` <a id="not-found" /> | 404 | Ресурс не найден или недоступен пользователю. | Проверьте идентификатор ресурса и права доступа. |
| `METHOD_NOT_ALLOWED` <a id="method-not-allowed" /> | 405 | HTTP-метод не поддерживается для этого адреса. | Проверьте метод операции в справочнике API. |
| `IDEMPOTENCY_IN_PROGRESS` <a id="idempotency-in-progress" /> | 409 | Запрос с этим ключом идемпотентности ещё выполняется. | Дождитесь завершения и повторите запрос с тем же ключом, чтобы получить сохранённый ответ. |
| `IDEMPOTENCY_CONFLICT` <a id="idempotency-conflict" /> | 409 | Не удалось определить состояние запроса с этим ключом идемпотентности. | Проверьте результат операции и при необходимости повторите её с новым ключом. |
| `IDEMPOTENCY_MISMATCH` <a id="idempotency-mismatch" /> | 409 | Ключ идемпотентности уже использован с другим телом запроса. | Для нового запроса используйте новый ключ; для повтора отправьте то же тело. |
| `CONFLICT` <a id="conflict" /> | 409 | Операция конфликтует с текущим состоянием ресурса. | Получите актуальное состояние ресурса и повторите операцию. |
| `PAYLOAD_TOO_LARGE` <a id="payload-too-large" /> | 413 | Тело запроса превышает допустимый размер. | Уменьшите размер тела запроса. |
| `UNPROCESSABLE_ENTITY` <a id="unprocessable-entity" /> | 422 | Запрос корректен по формату, но не может быть выполнен. | Устраните причину из поля `detail` и повторите запрос. |
| `RATE_LIMITED` <a id="rate-limited" /> | 429 | Превышен лимит частоты запросов. | Повторите запрос через число секунд из заголовка `Retry-After`. |
| `LLM_QUOTA_EXCEEDED` <a id="llm-quota-exceeded" /> | 429 | Команда исчерпала месячный лимит AI-ассистента. | AI-функции снова заработают с начала следующего месяца. Чтобы увеличить лимит раньше, обратитесь в поддержку. |
| `PERMISSION_CHECK_FAILED` <a id="permission-check-failed" /> | 500 | Не удалось проверить права доступа из-за временной ошибки. | Повторите запрос позже; если ошибка повторяется — обратитесь в поддержку и укажите `request_id`. |
| `INTERNAL` <a id="internal" /> | 500 | Внутренняя ошибка сервера. | Повторите запрос позже; если ошибка повторяется — обратитесь в поддержку и укажите `request_id`. |
| `UPSTREAM_UNAVAILABLE` <a id="upstream-unavailable" /> | 503 | Сервис временно недоступен. | Повторите запрос позже с экспоненциальной паузой. |
| `CIRCUIT_OPEN` <a id="circuit-open" /> | 503 | Сервис временно не принимает запросы из-за сбоев. | Повторите запрос позже с экспоненциальной паузой. |
| `REQUEST_TIMEOUT` <a id="request-timeout" /> | 504 | Сервер не успел обработать запрос. | Повторите запрос; для изменяющих запросов передавайте тот же `Idempotency-Key`, чтобы операция не выполнилась дважды. |