---
title: "Ошибки API: HTTP-коды"
description: Справочник HTTP-кодов ошибок API — значения, причины, решения. Форматы ответов для OMNI API, Broadcasts API и Recipients API
---
> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.mydialogi.ru/llms.txt). Append `.md` to any page URL for its markdown version.
> **Коротко:** API возвращает HTTP-коды. Каждый код показывает, что произошло. Формат тела ошибки отличается для разных API — смотрите таблицы ниже.
## Кому подходит
- Роль: Разработчик, Интегратор
- Уровень: Опытный
## Симптом
API возвращает код, отличный от ожидаемого, и вы не понимаете, что произошло.
## Два формата ответа с ошибкой
Формат ошибки зависит от API. Не ищите поле `error` в ответах Broadcasts API и Recipients API — там его нет.
### OMNI API
Используется в эндпоинтах `/api/v1/messages`, `/api/v1/omnimessages`, `/api/v1/senders`, `/api/v1/channels`, `/api/v1/balance`, `/api/v1/edrs`, `/api/v1/templates`, `/api/v1/wa_templates`.
| Поле | Тип | Что означает |
|---|---|---|
| `error` | boolean | `true` — запрос завершился ошибкой |
| `data.message` | string | Текст ошибки |
| `data.requestId` | string | ID запроса для обращения в поддержку |
**Пример:**
```json
{
"error": true,
"data": {
"message": "something went wrong",
"requestId": "af8c5065-5849-455b-ae1a-6a0b9f4b7209"
}
}
```
### Broadcasts API и Recipients API
Используется в эндпоинтах `/api/v1/broadcast/*` и `/api/v1/recipient/*`.
| Поле | Тип | Что означает |
|---|---|---|
| `execId` | string | ID выполнения (может быть пустым) |
| `key` | string | Ключ ошибки для локализации, например `errors.common_error` |
| `code` | string | Код ошибки, например `ValidationError` |
| `message` | string | Текст ошибки |
| `args` | object | Дополнительные аргументы (может быть пустым) |
**Пример:**
```json
{
"execId": null,
"key": "errors.common_error",
"code": "ValidationError",
"message": "Selected filter's attributes don't exist.",
"args": null
}
```
## Быстрый справочник кодов
Набор кодов зависит от эндпоинта. Полный список для каждого метода — в Swagger UI вашего сервиса.
| Код | Значение | Категория |
|---|---|---|
| 200 | OK | Успех |
| 202 | Accepted | Успех |
| 204 | No Content | Успех |
| 400 | Bad Request | Ошибка клиента |
| 401 | Unauthorized | Ошибка авторизации |
| 403 | Forbidden | Ошибка прав |
| 404 | Not Found | Ресурс не найден |
| 409 | Conflict | Конфликт данных |
| 422 | Unprocessable Entity | Невалидные данные |
| 429 | Too Many Requests | Превышен лимит |
| 500 | Internal Server Error | Ошибка сервера |
| 502 | Bad Gateway | Ошибка шлюза |
| 503 | Service Unavailable | Сервис недоступен |
## Описание кодов и решения
### Успех: 200, 202, 204
**200 OK** — запрос обработан успешно. Тело содержит результат.
**202 Accepted** — запрос принят. Используется в OMNI API: сообщение поставлено в очередь на отправку.
Статус доставки можно получить двумя способами:
- **Push** — платформа сама отправит статус на ваш вебхук, когда сообщение изменит состояние.
- **Pull** — вы запрашиваете статусы самостоятельно через эндпоинт `GET /edrs`.
О способах получения статусов для вашего сервиса:
- [Статусы в OTP-кодах →](https://docs.mydialogi.ru/02-otp/08-api/otp-api-statuses)
- [Статусы в Multi API →](https://docs.mydialogi.ru/03-multiapi/02-api/mapi-106-api-statuses)
- [Статусы в «Мой диалог» →](https://docs.mydialogi.ru/04-mydialogi/09-api/md-api-statuses)
**204 No Content** — запрос выполнен, но тело пустое. Используется при удалении — шаблоны рассылок, атрибуты, получатели.
### 400 Bad Request
**Что значит:** неверные параметры запроса.
**Решение:**
1. Проверьте формат JSON — нет ли лишних запятых или кавычек.
2. Проверьте обязательные поля: `contact`, `channel`, `senderId`, `phoneNumber`, `type`.
3. Проверьте типы значений — числа не в кавычках, строки в кавычках.
4. Проверьте формат номера телефона — с кодом страны, без «+».
**Частые сообщения:**
- `Phone number can't be null or empty`
- `Recipient type can't be null`
- `Selected filter's attributes don't exist.`
[Обработка ошибок API →](https://docs.mydialogi.ru/06-reference/01-api/api-errors)
### 401 Unauthorized
**Что значит:** неверный или отсутствующий API-ключ.
**Решение:**
1. Проверьте, что заголовок `X-API-Key` передан в запросе.
2. Проверьте, что ключ активен и не удалён.
3. Проверьте, что ключ от нужного сервиса — ключ от OTP не работает на Multi API.
4. Если старый ключ удалён — создайте новый.
[Ошибка 401 и 403 →](https://docs.mydialogi.ru/06-reference/03-troubleshooting/ts-auth-401-403)
### 403 Forbidden
**Что значит:** у ключа нет нужного права (scope).
**Решение:**
1. Откройте настройки ключа в разделе **API Подключения**.
2. Проверьте список scopes.
3. Добавьте нужный scope: `omni-api`, `statistics`, `recipients`, `broadcasts`, `dids`, `crm`.
4. Сохраните изменения.
[Ошибка 401 и 403 →](https://docs.mydialogi.ru/06-reference/03-troubleshooting/ts-auth-401-403)
### 404 Not Found
**Что значит:** неверный URL или несуществующий ID.
**Решение:**
1. Проверьте базовый URL вашего сервиса — `web.otpcod.ru`, `web.multiapi.ru`, `web.mydialogi.ru`.
2. Проверьте ID ресурса: шаблона, получателя, рассылки.
3. Проверьте метод запроса (GET, POST, PUT, DELETE).
### 409 Conflict
**Что значит:** конфликт данных — например, попытка создать дубликат.
**Решение:**
1. Проверьте, не создан ли уже такой ресурс.
2. Используйте уникальные идентификаторы.
3. Если конфликт по email — используйте номер телефона (он уникален).
### 422 Unprocessable Entity
**Что значит:** данные не прошли валидацию.
**Решение:**
1. Проверьте формат email.
2. Проверьте формат номера телефона.
3. Проверьте длину полей — не превышены ли лимиты.
4. Проверьте, что значения соответствуют допустимым — например, `type` только `ENRICH`, `NOT_IMPORT` или `OVERWRITE`.
### 429 Too Many Requests
**Что значит:** превышен лимит запросов.
**Решение:**
1. Уменьшите частоту запросов.
2. Используйте очереди.
3. Обратитесь в поддержку, если лимит критично низкий.
[Ошибка 429 →](https://docs.mydialogi.ru/06-reference/03-troubleshooting/ts-rate-limit-429)
### 500 Internal Server Error
**Что значит:** ошибка на стороне сервера.
**Решение:**
1. Повторите запрос через 30 секунд.
2. Сохраните `requestId` (OMNI API) или `execId` (Broadcasts и Recipients).
3. Если ошибка повторяется — обратитесь в поддержку с этими идентификаторами.
### 502 Bad Gateway
**Что значит:** ошибка шлюза между сервисами.
**Решение:**
1. Повторите запрос через 10–30 секунд.
2. Если повторяется — обратитесь в поддержку.
### 503 Service Unavailable
**Что значит:** сервис временно недоступен — идут технические работы или перегрузка.
**Решение:**
1. Подождите 1–2 минуты.
2. Повторите запрос.
3. Если не помогает — обратитесь в поддержку.
## Как узнать requestId или execId
Сохраняйте эти идентификаторы при любой ошибке — они помогут поддержке быстрее найти проблему.
| API | Поле | Где в ответе |
|---|---|---|
| OMNI API | `requestId` | В `data` объекта ответа |
| Broadcasts API | `execId` | В корне объекта ответа |
| Recipients API | `execId` | В корне объекта ответа |
**Пример для OMNI API:**
```json
{
"error": true,
"data": {
"message": "something went wrong",
"requestId": "af8c5065-5849-455b-ae1a-6a0b9f4b7209"
}
}
```
## См. также
Форматы ошибок для каждого API
Что делать при ошибках авторизации
Что делать при превышении лимита
Куда обращаться по сервисам
## Нужна помощь?
- OTP-коды: support@otpcod.ru
- Multi API: support@multiapi.ru
- Мой диалог: support@mydialogi.ru