Добавить контакт

Сопоставляйте HTTP-статус, error.code и error.numeric_code с текущей операцией. Числовой код — строка. Сохраняйте request_id для диагностики: это не ключ идемпотентности и не идентификатор задачи.

invalid_request · 10000 · 400

Проверьте JSON и обязательные поля.

Действия и повторы: Исправьте параметры с учётом операции и канала. Повтор неизменённого неверного запроса не устранит ошибку.

Пример JSON; message зависит от фактической причины · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

Целевое рабочее пространство в заголовке переопределения пусто или задано неверно. Удалите этот заголовок и используйте API-ключ нужного пространства.

Условие: Применяется к запросам с заголовком переопределения рабочего пространства X-Workspace-Id.

Действия и повторы: Исправьте параметры с учётом операции и канала. Повтор неизменённого неверного запроса не устранит ошибку.

Пример JSON; message зависит от фактической причины · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

provider_invalid_request · 30001 · 400

Проверьте поля и форматы, специфичные для канала.

Действия и повторы: Исправьте параметры с учётом операции и канала. Повтор неизменённого неверного запроса не устранит ошибку.

Пример JSON; message зависит от фактической причины · 400 · 30001

{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}

invalid_api_key · 11001 · 401

Проверьте правильность и активность ключа API.

Действия и повторы: Сохраните request_id и структурированные коды; выясните причину текущего сбоя перед следующим действием.

Пример JSON; message зависит от фактической причины · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

Добавьте заголовок X-Api-Key.

Действия и повторы: Сохраните request_id и структурированные коды; выясните причину текущего сбоя перед следующим действием.

Пример · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

workspace_override_forbidden · 11002 · 403

Запрос пытается переопределить рабочее пространство без необходимых прав. Удалите заголовок переопределения и используйте API-ключ нужного рабочего пространства.

Условие: Применяется к запросам с заголовком переопределения рабочего пространства X-Workspace-Id.

Действия и повторы: Сохраните request_id и структурированные коды; выясните причину текущего сбоя перед следующим действием.

Пример JSON; message зависит от фактической причины · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

target_workspace_not_found · 11004 · 404

Переопределённое рабочее пространство не найдено или недоступно. Проверьте его принадлежность, удалите заголовок переопределения и используйте нужный API-ключ; повторы не дадут доступ.

Условие: Применяется к запросам с заголовком переопределения рабочего пространства X-Workspace-Id.

Действия и повторы: Проверьте идентификатор, принадлежность ресурса и текущее рабочее пространство. Не повторяйте запрос автоматически, считая подтверждённое отсутствие или недоступность временным сбоем сервиса.

Пример JSON; message зависит от фактической причины · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

account_binding_not_found · 30006 · 409

Нет активной привязки к подключению канала; проверьте состояние аккаунта.

Действия и повторы: Проверьте авторизацию и runtime-статус, затем выберите refresh, start или reconnect с учётом нужного состояния и возможностей канала. Сбой соединения сам по себе не означает выход из аккаунта. Перед зависимыми операциями подтвердите running.

Пример JSON; message зависит от фактической причины · 409 · 30006

{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}

egress_configuration_pending · 20032 · 409

Сейчас невозможно подтвердить или загрузить сетевую конфигурацию платформы по умолчанию. Это не означает выход аккаунта из системы.

Условие: Операция использует выделяемую платформой сетевую ёмкость или закреплённую за аккаунтом конфигурацию сети по умолчанию.

Действия и повторы: Сохраните request_id и проверьте аккаунт или результат создания перед повторной записью. Дождитесь восстановления ёмкости или конфигурации либо обратитесь в поддержку. Не создавайте аккаунты, не меняйте сеть и не перезапускайте их автоматически снова и снова.

Пример JSON; message зависит от фактической причины · 409 · 20032

{
  "request_id": "req_example",
  "error": {
    "code": "egress_configuration_pending",
    "numeric_code": "20032",
    "message": "Account network configuration is pending verification"
  }
}

provider_not_ready · 30009 · 409

Подключение не готово. Перед повтором проверьте авторизацию и runtime_status.

Действия и повторы: Проверьте авторизацию и runtime-статус, затем выберите refresh, start или reconnect с учётом нужного состояния и возможностей канала. Сбой соединения сам по себе не означает выход из аккаунта. Перед зависимыми операциями подтвердите running.

Пример JSON; message зависит от фактической причины · 409 · 30009

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}

provider_not_ready · 30014 · 409

Отсутствует экземпляр провайдера, нужный аккаунту. Это проблема доступности среды выполнения, а не доказательство истечения авторизации.

Действия и повторы: Проверьте авторизацию и runtime-статус, затем выберите refresh, start или reconnect с учётом нужного состояния и возможностей канала. Сбой соединения сам по себе не означает выход из аккаунта. Перед зависимыми операциями подтвердите running.

Каналы: WhatsApp

Пример JSON; message зависит от фактической причины · 409 · 30014

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30014",
    "message": "Provider instance is missing"
  }
}

provider_not_ready · 30015 · 409

Среда выполнения провайдера остановлена. Перед запуском выясните, не было ли это намеренным; остановка сама по себе не означает выход из аккаунта.

Действия и повторы: Проверьте авторизацию и runtime-статус, затем выберите refresh, start или reconnect с учётом нужного состояния и возможностей канала. Сбой соединения сам по себе не означает выход из аккаунта. Перед зависимыми операциями подтвердите running.

Каналы: WhatsApp

Пример JSON; message зависит от фактической причины · 409 · 30015

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30015",
    "message": "Provider runtime is stopped"
  }
}

create_contact_failed · 20020 · 500

Проверьте account_id и используйте X-Api-Key рабочего пространства владельца аккаунта. Текущий ключ не даёт доступа к аккаунту, которого нет в этом пространстве.

Условие: Применяется, когда аккаунт не найден: прежние HTTP-статус и код операции сохраняются, а numeric_code уточняет отсутствие аккаунта.

Действия и повторы: Проверьте идентификатор, принадлежность ресурса и текущее рабочее пространство. Не повторяйте запрос автоматически, считая подтверждённое отсутствие или недоступность временным сбоем сервиса.

Пример JSON; message зависит от фактической причины · 500 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

create_contact_failed · 30010 · 500

Провайдер не выполнил операцию. message может содержать исходную причину после «Provider operation failed:»; текст меняется и не является стабильным программным интерфейсом.

Условие: Применяется, когда канал не сообщает более точную категорию сбоя; сохраняется ошибка текущей операции.

Действия и повторы: Перед повторным созданием проверьте список или состояние ресурсов: возможно, первая попытка уже сработала. Устраните причину и сохраните request_id; не создавайте дубликаты автоматически.

Каналы: WhatsApp

Пример JSON; message зависит от фактической причины · 500 · 30010

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}

create_contact_failed · 30017 · 500

Канал явно отклонил запрос из-за слишком высокой частоты. Числовая классификация сохраняет прежние HTTP-статус и code операции.

Действия и повторы: Приостановите запросы и повторите позже с ограничением числа попыток. Фиксированная задержка и обработка Retry-After здесь не гарантированы. Перед повторной записью выясните предыдущий результат.

Каналы: WhatsApp

Пример JSON; message зависит от фактической причины · 500 · 30017

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "30017",
    "message": "Provider rate limit exceeded"
  }
}

create_contact_failed · 30018 · 500

Базовый App State аккаунта рассинхронизирован у провайдера. Это состояние синхронизации аккаунта, а не обычная ошибка формата запроса.

Действия и повторы: Дождитесь восстановления базового App State у провайдера, затем проверьте состояние перед повтором. Эта классификация сама по себе не означает недействительные учётные данные и не требует новой авторизации.

Каналы: WhatsApp

Пример JSON; message зависит от фактической причины · 500 · 30018

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "30018",
    "message": "Provider app state is out of sync"
  }
}

create_contact_failed · 30021 · 500

Во время этого запроса аккаунт не был подключён к платформе обмена сообщениями. При добавлении контакта WhatsApp возможен ответ 500 / create_contact_failed / 30021. Это не доказывает выход из аккаунта или сохранение текущего состояния disconnected. Сначала запросите текущее состояние, затем выберите способ восстановления.

Действия и повторы: Приостановите операции, которым нужно соединение. Сначала вызовите POST /v1/accounts/{account_id}/runtime/refresh, восстановите соединение по актуальному состоянию и подтвердите runtime_status=running перед бизнес-запросами. Перед повторной отправкой выясните результат предыдущей записи.

Каналы: WhatsApp

Пример JSON; message зависит от фактической причины · 500 · 30021

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "30021",
    "message": "Account is not connected to the messaging platform"
  }
}

create_contact_failed · 35003 · 500

Добавить контакт: создание ресурса завершилось ошибкой или его результат не подтверждён.

Действия и повторы: Перед повторным созданием проверьте список или состояние ресурсов: возможно, первая попытка уже сработала. Устраните причину и сохраните request_id; не создавайте дубликаты автоматически.

Пример JSON; message зависит от фактической причины · 500 · 35003

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "35003",
    "message": "Failed to create contact"
  }
}

create_contact_failed · 35009 · 500

В этом запросе WhatsApp не распознал целевой номер как активный контакт. Это не доказывает отсутствие регистрации или постоянную недоступность номера.

Действия и повторы: Уточните у пользователя код страны, номер и регистрацию WhatsApp, затем проверьте error.message. Повторяйте запрос только после проверки причины; не отправляйте один и тот же номер автоматически многократно.

Каналы: WhatsApp

Пример · 500 · 35009

{
  "request_id": "req_example_contact_not_active",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "35009",
    "message": "Target phone number was not recognized as an active WhatsApp contact"
  }
}

unsupported_by_provider · 30003 · 501

Канал не поддерживает операцию; выберите доступную в таблице возможностей.

Действия и повторы: Выберите поддерживаемые канал и действие. Повтор запроса не добавит возможностей и не откроет доступ к бета-функциям.

Пример · 501 · 30003

{
  "request_id": "req_xxx",
  "error": {
    "code": "unsupported_by_provider",
    "numeric_code": "30003",
    "message": "Operation not supported by this provider"
  }
}

provider_adapter_not_found · 30004 · 502

Сервис канала недоступен. Проверьте состояние или повторите позже; перед повтором записи проверьте предыдущий результат.

Действия и повторы: Перед повторным созданием проверьте список или состояние ресурсов: возможно, первая попытка уже сработала. Устраните причину и сохраните request_id; не создавайте дубликаты автоматически.

Пример JSON; message зависит от фактической причины · 502 · 30004

{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}

provider_unavailable · 30002 · 502

Сервис канала недоступен. Проверьте состояние или повторите позже; перед повтором записи проверьте предыдущий результат.

Действия и повторы: Перед повторным созданием проверьте список или состояние ресурсов: возможно, первая попытка уже сработала. Устраните причину и сохраните request_id; не создавайте дубликаты автоматически.

Пример · 502 · 30002

{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}

provider_unavailable · 30010 · 502

Провайдер не выполнил операцию. message может содержать исходную причину после «Provider operation failed:»; текст меняется и не является стабильным программным интерфейсом.

Действия и повторы: Перед повторным созданием проверьте список или состояние ресурсов: возможно, первая попытка уже сработала. Устраните причину и сохраните request_id; не создавайте дубликаты автоматически.

Каналы: WhatsApp

Пример · 502 · 30010

{
  "request_id": "req_example_operation_failed",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30010",
    "message": "Provider operation failed: Example operation could not be completed"
  }
}

provider_unavailable · 30021 · 502

Во время этого запроса аккаунт не был подключён к платформе обмена сообщениями. При добавлении контакта WhatsApp возможен ответ 500 / create_contact_failed / 30021. Это не доказывает выход из аккаунта или сохранение текущего состояния disconnected. Сначала запросите текущее состояние, затем выберите способ восстановления.

Действия и повторы: Приостановите операции, которым нужно соединение. Сначала вызовите POST /v1/accounts/{account_id}/runtime/refresh, восстановите соединение по актуальному состоянию и подтвердите runtime_status=running перед бизнес-запросами. Перед повторной отправкой выясните результат предыдущей записи.

Каналы: WhatsApp

Пример · 502 · 30021

{
  "request_id": "req_example_connection_disconnected",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30021",
    "message": "example operation: websocket not connected"
  }
}