Ошибки

Любая ошибка — HTTP-статус и JSON с машинным кодом error.code, понятным текстом и, когда есть, подробностями.

{
  "error": {
    "code": "unsupported",
    "message": "max does not support \"poll\"",
    "details": {}
  }
}

Решения в коде принимайте по status и error.code; message предназначен человеку и может меняться.

Все коды

HTTP	`error.code`	Что значит и что делать
400	`bad_request`	Запрос не прошёл проверку. В `details` — список полей: `[{path, message}]`.
401	`unauthorized`	Нет ключа, ключ неверный или клиент приостановлен.
402	`billing_suspended`	Срок оплаты номера истёк: отправка заблокирована, приём сообщений продолжается. Продлите номер.
403	`forbidden`	Действие запрещено (например, удалить номер, подключённый оператором; запись из консоли без CSRF-токена).
403	`quota_exceeded`	Достигнут лимит номеров клиента или самообслуживание выключено. `details: {limit, used}`.
403	`billing_managed_by_platform`	Срок оплаты ваших номеров ведёт оператор, а не вы.
403	`billing_managed_by_tenant`	Вы сами ведёте оплату своих пользователей — счета платформы вам не нужны.
404	`not_found`	Объекта нет или он принадлежит другому клиенту. Неизвестный адрес метода — тоже 404.
409	`account_not_ready`	Номер не авторизован, заблокирован или ждёт облачный пароль. `details.state` — состояние.
409	`groups_disabled`	Отправка в группу или канал, а группы у номера выключены.
409	`attachment_not_ready`	Файл ещё скачивается или не сохранился.
409	`message_not_sent`	Сообщение ещё не ушло в мессенджер — править или удалять рано.
409	`message_deleted`	Сообщение уже удалено.
409	`quote_not_sent`, `forward_not_sent`	Цитируемое или пересылаемое сообщение ещё не отправлено.
409	`story_not_sent`	Статистика просмотров есть только у отправленных сторис.
409	`billing_suspended`	Сторис: номер приостановлен за неоплату.
409	`order_in_progress`	Заказ номера с этим `clientId` ещё выполняется — повторите через несколько секунд.
409	`idempotency_mismatch`	Этот `clientId` уже использован для заказа другого мессенджера.
409	`idempotency_key_used`	Номер с этим `clientId` был удалён — нужен новый `clientId`.
409	`instance_exists`	Оператор: этот инстанс GREEN-API уже подключён.
409	`account_exists`	Оператор: номер с таким `id` уже есть (восстановление под прежним id).
409	`secrets_key_required`, `managed_by_env`	Оператор: настройки оплаты нельзя сохранить (нет ключа шифрования или они заданы в окружении сервера).
413	`too_large`	Файл больше допустимого размера.
422	`unsupported`	Мессенджер номера не умеет эту операцию (см. Мессенджеры), или заказ номеров этого мессенджера недоступен.
422	`payments_disabled`	Онлайн-оплата на платформе не настроена.
422	`no_price`, `unsupported_currency`	Для мессенджера номера нет цены в прайс-листе, или прайс не в рублях.
429	`rate_limited`	Слишком много заказов номеров или счетов за час. `details.retryAfterSec` — через сколько повторить.
429	`too_many_attempts`	Консоль: слишком много попыток входа с этого адреса.
502	`upstream_error`	Мессенджер-провайдер не ответил или ответил ошибкой. `details.kind`: `network`, `timeout`, `rate_limit`, `quota`, `auth`, `validation`, `server`. Можно повторить позже.
500	`internal_error`	Ошибка на нашей стороне. Повторите позже; если повторяется — сообщите оператору время запроса.

Повторы

5xx, 429 и сетевые ошибки можно повторять с паузой. Для отправки обязательно передавайте clientId, чтобы повтор не создал дубль.
4xx (кроме 409 order_in_progress и 429) повторять без изменений бессмысленно — исправьте запрос.