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

Что это такое

YCloud использует коды состояния HTTP и структурированное тело ошибки, чтобы ваше приложение могло определить, нужно ли исправить запрос, отклонить его или повторить попытку.

Ответ

При неудачном выполнении запроса возвращается объект error.

{
  "error": {
    "status": 404,
    "code": "NOT_FOUND",
    "message": "The requested resource does not exist.",
    "requestId": "req_1KjtKI80IKoaJNa6n6p"
  }
}

Поля ошибки

Поле	Описание
`status`	Обязательный код состояния HTTP, возвращаемый API.
`code`	Обязательный машиночитаемый код ошибки YCloud.
`message`	Пояснение для разработчиков. Не показывайте его конечным пользователям напрямую.
`target`	Поле запроса или ресурс, связанный с ошибкой, если применимо.
`docUrl`	Ссылка на дополнительную информацию, если доступна.
`requestId`	Идентификатор запроса, также возвращаемый в заголовке `YCloud-Request-ID`, для отслеживания запроса службой поддержки YCloud.
`whatsappApiError`	Исходные данные об ошибке WhatsApp, если прямой запрос к WhatsApp API достиг Meta и завершился ошибкой.

Коды ошибок

Используйте error.code для различения ошибок с одинаковым статусом HTTP. В этом перечне представлены коды ошибок YCloud API; конкретный эндпоинт может содержать описание дополнительных ошибок.

Код	Статус HTTP	Значение и действие
`ACCOUNT_LIMITED`	`403`	Ограничение аккаунта препятствует выполнению действия. Например, пробный аккаунт может отправлять сообщения только на предварительно подтвержденные номера. Проверьте действующие ограничения аккаунта.
`ACCOUNT_RATE_LIMITED`	`429`	Квота аккаунта исчерпана. Приостановите запросы, использующие эту квоту, и соблюдайте `Retry-After`.
`ACCOUNT_UNAVAILABLE`	`403`	Аккаунт недоступен. Обратитесь в службу поддержки YCloud.
`ALREADY_EXISTS`	`409`	Ресурс уже существует. Проверьте существующие ресурсы и параметры запроса перед созданием нового.
`BAD_REQUEST`	`400`	Недопустимые параметры запроса. Исправьте запрос, используя подробные сведения об ошибке.
`BALANCE_INSUFFICIENT`	`403`	На балансе аккаунта недостаточно средств. Пополните баланс перед повторной попыткой.
`CONTENT_PROHIBITED`	`403`	Контент нарушает условия использования сервиса. Исправьте или удалите запрещенный контент.
`CONTENT_TOO_LARGE`	`413`	Размер содержимого запроса слишком велик. Уменьшите его размер.
`EMAIL_DOMAIN_UNVERIFIED`	`403`	Домен электронной почты не подтвержден. Завершите подтверждение и подождите, пока изменения вступят в силу.
`FORBIDDEN`	`403`	У вас нет доступа к ресурсу. Проверьте права владения и разрешения вашего аккаунта.
`INTERNAL_SERVER_ERROR`	`500`	В YCloud произошла ошибка сервера. Повторите попытку при временных сбоях с ограниченной экспоненциальной задержкой в соответствии с правилами повторов для данной операции.
`MESSAGING_REGION_UNSUPPORTED`	`400`	Отправка сообщений в запрошенный регион не поддерживается. Проверьте направление.
`NOT_FOUND`	`404`	Ресурс не существует. Проверьте его ID и путь к эндпоинту.
`PARAM_INVALID`	`400`	Недопустимое значение параметра. Исправьте поле, указанное в подробных сведениях об ошибке.
`PARAM_INVALID_LENGTH`	`400`	Длина параметра выходит за допустимые пределы. Проверьте ограничения для данного поля.
`PARAM_MISSING`	`400`	Отсутствует обязательный параметр. Добавьте его в запрос.
`PARAM_NOT_MATCH`	`400`	Два или более параметров несовместимы. Проверьте обязательную взаимосвязь между ними.
`RECIPIENT_IN_BLOCK_LIST`	`403`	Получатель заблокирован. Проверьте черный список аккаунта перед отправкой.
`RECIPIENT_UNSUBSCRIBED`	`403`	Получатель отписался. Учитывайте отказ от рассылки и проверьте записи об отписках.
`SENDER_ID_UNAVAILABLE`	`403`	SMS Sender ID не зарегистрирован или все еще находится на рассмотрении. Проверьте статус его регистрации.
`SENDER_RATE_LIMITED`	`429`	Квота отправителя исчерпана. Снизьте частоту запросов для этого отправителя и соблюдайте `Retry-After`.
`SERVICE_UNAVAILABLE`	`503`	Сервис временно недоступен или перегружен. Повторите попытку позже, если это безопасно для выполняемой операции.
`SMS_SIGNATURE_UNAVAILABLE`	`403`	Подпись для SMS материкового Китая недоступна. Проверьте подпись SMS.
`TOO_MANY_REQUESTS`	`429`	Запросы поступают слишком часто. Учитывайте `Retry-After` и снижайте объем трафика с помощью задержек (backoff) и джиттера.
`UNAUTHORIZED`	`401`	Ошибка аутентификации. Проверьте ключ API в `X-API-Key`.
`WHATSAPP_PHONE_NUMBER_UNAVAILABLE`	`403`	Номер телефона WhatsApp недоступен. Проверьте номер отправителя.
`WHATSAPP_TEMPLATE_UNAVAILABLE`	`403`	Шаблон WhatsApp отсутствует или не одобрен. Проверьте его название и статус.
`WHATSAPP_WABA_UNAVAILABLE`	`403`	WhatsApp Business Account недоступен. Проверьте идентификатор WABA ID, используемый в запросе.
`WHATSAPP_TEMPLATE_UNEDITABLE`	`403`	Шаблон не может быть отредактирован в текущем статусе. Для редактирования требуется статус `APPROVED`, `REJECTED` или `PAUSED`.

Информацию о квотах учетной записи и отправителя см. в разделе Лимиты запросов. Ошибки Meta также могут отображаться в error.whatsappApiError после того, как запрос достигает WhatsApp. Сохраняйте эти сведения вместе с кодом ошибки YCloud.

Как обрабатывать ответ

Статус	Рекомендуемое действие
`400`	Исправьте параметры или тело запроса.
`401`	Проверьте ключ API. Не повторяйте попытку с неизмененными учетными данными.
`403`	Используйте `error.code`, чтобы проверить ограничения учетной записи, баланса, получателя или ресурса. Устраните причину перед повторной попыткой.
`404`	Проверьте идентификатор ресурса и путь эндпоинта.
`429`	Учитывайте `Retry-After`, снижайте объем трафика и используйте ограниченную задержку повтора.
`5xx`	Повторяйте запросы при временных сбоях с экспоненциальной задержкой и джиттером.

Корреляция запросов

Логируйте эндпоинт, метод HTTP, статус ответа, YCloud requestId и ваш собственный идентификатор корреляции. Удаляйте ключи API и персональные данные. Это предоставит вам достаточно информации для расследования сбоя без раскрытия конфиденциальных данных.

Безопасное повторение запросов

Повторяйте запросы, предназначенные только для чтения, если сбой носит временный характер. Соблюдайте осторожность при отправке сообщений и выполнении других операций создания. Повторный запрос POST может создать второй ресурс или отправить дублирующееся сообщение. Если схема запроса это поддерживает, укажите в externalId уникальное значение из вашей системы. Сохраняйте идентификатор ответа YCloud после успешного выполнения запроса.

При обращении в службу поддержки YCloud укажите requestId, эндпоинт, статус HTTP и время сбоя. Предварительно удалите ключи API и персональные данные.

Чек-лист по интеграции

Анализируйте ошибки по полю code, а не по сопоставлению текста в message.
Устанавливайте таймауты для каждого исходящего запроса.
Повторяйте только временные сбои.
Используйте экспоненциальную задержку, джиттер и ограничение максимального количества попыток.
Предотвращайте дублирование эффектов POST с помощью собственного стабильного идентификатора, когда запрос это поддерживает.

Начало работы

Руководства

Конечные точки

Webhooks

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

Что это такое

Ответ

Поля ошибки

Коды ошибок

Как обрабатывать ответ

Корреляция запросов

Безопасное повторение запросов

Чек-лист по интеграции

​Что это такое

​Ответ

​Поля ошибки

​Коды ошибок

​Как обрабатывать ответ

​Корреляция запросов

​Безопасное повторение запросов

​Чек-лист по интеграции

Что это такое

Ответ

Поля ошибки

Коды ошибок

Как обрабатывать ответ

Корреляция запросов

Безопасное повторение запросов

Чек-лист по интеграции