> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Обработка ошибок

> Ответ GOWA, коды ошибок и HTTP статусы, и как с ними работать.

## Конверт ответа

Каждый ответ JSON имеет ту же форму:

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Success",
  "results": { }
}
```

| Поле | Описание |
| - | - |
| `code` | `SUCCESS` или код ошибки. Используйте это значение вместе с HTTP-статусом для выбора дальнейших действий. |
| `message` | Детали в читаемых словах могут быть изменены между выпусками; не разбирайте их. |
| `results` | Загрузка на успех. Обычно пропущена по ошибкам. |

## Коды ошибок

| Код | HTTP | Значение | Что делать |
| - | - | - | - |
| `VALIDATION_ERROR` | 400 | Поле `message` отсутствует или недопустимо. | Исправить запрос. |
| `INVALID_JID` | 400 | Номер не найден в WhatsApp, или неправильный формат JID. | Проверьте номер; повторите попытку. |
| `ALREADY_LOGGED_IN` | 400 | Логин запрошен для устройства, которое уже авторизовано. | Ничего и ничего не выйти. |
| `DEVICE_ID_REQUIRED` | 400 | Не указано устройство и на сервере есть нулевое или несколько устройств. | Отправить `X-Device-Id`. |
| `AUTHENTICATION_ERROR` | 401 | Устройство не авторизовано в WhatsApp (или аутентификация WhatsApp не удалась). | Проверить `/devices/{id}/status`; при необходимости снова пар. |
| `NOT_FOUND` | 404 | Ресурс не найден (сообщение, чат, расписание…). | Проверьте ID. |
| `DEVICE_NOT_FOUND` | 404 | `X-Device-Id` называет неизвестное устройство. | Проверьте слот ID или JID. |
| `AVATAR_HIDDEN` | 403 | Изображение профиля скрыто в настройках конфиденциальности. | Не принимайте это как подтвержденное отсутствие или удаляйте кешированную картинку только на этом результате. |
| `AVATAR_NOT_SET` | 404 | У контакта нет изображения профиля. | Очистить кэшированное изображение только после проверки этого кода, а не 404. |
| `CROSS_SITE_REQUEST_BLOCKED` | 403 | Происхождение браузера не доверяет. | Serve the dashboard over HTTP(S) and configure the exact trusted origin. |
| `CONTEXT_ERROR` | 408 | Операция была отменена или прекращена внутри системы. | Повторите попытку один раз. |
| `WA_REACHOUT_TIMELOCK` | 429 | WhatsApp временно блокирует новые чаты этой учетной записи. | Остановить прошивку; см. [Пределы отправки](https://gowa-docs.mintlify.site/ru/advanced/rate-limiting.md). |
| `INTERNAL_SERVER_ERROR` | 500 | Неожиданный сбой, включая восстановленные паники. | Повторите попытку с backoff; проверьте журналы. |
| `QR_CHANNEL_ERROR` | 500 | Не удалось получить QR-код. | Повторить вход. |
| `SESSION_SAVED_ERROR` | 500 | Сессию не удалось сохранить. | Проверить хранилище и разрешения. |
| `UPLOAD_MEDIA_ERROR` | 500 | Не удалось загрузить медиа в WhatsApp. | Повторите попытку; проверьте размер и формат. |
| `WEBHOOK_ERROR` | 500 | Ошибка конфигурации или доставки вебхука. | Проверьте Webhook URL. |
| `INVALID_WA_CLI` | 500 | Клиент WhatsApp на устройстве не инициализирован. | Переподключиться или войти снова. |
| `DEVICE_MANAGER_UNAVAILABLE` | 503 | Менеджер устройства не инициализирован. | Повторите попытку в ближайшее время; проверьте журналы запуска. |
| `GATEWAY_TIMEOUT` | 504 | Запрос превысил 45 секунд. | Действие все еще может быть завершено; проверьте перед попыткой. |

При ошибках Basic Auth уровень аутентификации возвращает `401` до вызова обработчиков GOWA; считайте любой ответ `401` без поля GOWA `code` признаком неверных учётных данных.

## Повторная попытка

Отправка **не idempotent**: GOWA не имеет ключа idempotence. Если время отправки (`504`, ошибка сети), сообщение уже может быть доставлено. Перед повторной отправкой проверьте чат с помощью `GET /chat/{chat_jid}/messages?is_from_me=true&limit=5`, или согласитесь с риском дубликата.

| Повторить | Не повторять |
| - | - |
| `500 INTERNAL_SERVER_ERROR`, `UPLOAD_MEDIA_ERROR`, `CONTEXT_ERROR`, `503` | Ошибка `400`, `INVALID_JID`, `404`, `401`, `WA_REACHOUT_TIMELOCK` |

Используйте экспоненциальный бэк-офф с записью и ограничивайте попытки.

```javascript theme={null}
async function gowa(path, body, attempt = 1) {
  const res = await fetch(`http://localhost:3000${path}`, {
    method: "POST",
    headers: {
      Authorization: "Basic " + Buffer.from("admin:changeme").toString("base64"),
      "Content-Type": "application/json",
      "X-Device-Id": "my-device",
    },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (res.ok) return data.results;

  const retryable = [500, 503].includes(res.status) && data.code !== "INVALID_JID";
  if (retryable && attempt < 4) {
    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
    return gowa(path, body, attempt + 1);
  }
  throw Object.assign(new Error(data.message || res.statusText), { code: data.code, status: res.status });
}
```

## Отладка

* Запустите `APP_DEBUG=true` для детальных журналов.
* Проверьте устройство: `GET /devices/{device_id}/status` (`is_connected`, `is_logged_in`).
* `GET /health` только подтверждает процесс и базу данных включена; она не проверяет подключение WhatsApp.


## Related topics

- [Ошибки](https://gowa-docs.mintlify.site/ru/api-reference/errors.md)
- [Обработка файлов](https://gowa-docs.mintlify.site/ru/examples/media-handling.md)
- [Интеграция с Chatwoot](https://gowa-docs.mintlify.site/ru/integrations/chatwoot.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.