# Ошибки

> Формат ошибок Problem Details (RFC 9457) и каталог кодов.

API возвращает ошибки в формате [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) с `Content-Type: application/problem+json`:

Ответ 400:

```json
{
  "type": "https://legalstack.ru/errors/validation-failed",
  "title": "Некорректный запрос",
  "status": 400,
  "code": "VALIDATION_FAILED",
  "errors": [{ "pointer": "/email", "name": "email", "reason": "Неверный email адрес" }],
  "instance": "/api/v1/security/users",
  "request_id": "req_01hzx..."
}
```

Как читать ответ:

- `code` — стабильный машиночитаемый идентификатор; ветвите обработку по нему, а не по тексту.
- `title` и `detail` — текст для человека на русском языке (заголовок ответа `Content-Language: ru`); `title` соответствует HTTP-статусу, `detail` поясняет конкретный случай.
- `type` — URL вида `https://legalstack.ru/errors``/<код-в-kebab-case>`, ведёт на описание ошибки в этой документации.
- `errors` — для ошибок валидации: список полей с JSON Pointer и причиной на русском языке.
- `request_id` / `trace_id` — идентификаторы для обращения в поддержку.
- При `429` и `503` дополнительно приходит заголовок `Retry-After`.

Полный перечень кодов — в [каталоге ошибок](https://docs.legalstack.ru/errors).