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

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

> Узнайте о структуре ответов с ошибками в YCloud и о безопасных повторных попытках отправки запросов.

## Что это такое

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

## Ответ

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`. |

Информацию о квотах учетной записи и отправителя см. в разделе [Лимиты запросов](/ru/api-reference/guides/api-fundamentals/rate-limits).
Ошибки Meta также могут отображаться в `error.whatsappApiError` после того, как запрос достигает
WhatsApp. Сохраняйте эти сведения вместе с кодом ошибки YCloud.

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

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

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

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

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

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

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

<Tip>
  При обращении в [службу поддержки YCloud](mailto:service@ycloud.com) укажите `requestId`, эндпоинт, статус HTTP и время сбоя. Предварительно удалите ключи API и персональные данные.
</Tip>

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

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


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