> ## 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.

# Handle errors

> Understand YCloud error responses and retry requests safely.

## What it is

YCloud uses HTTP status codes and a structured error body so your application
can decide whether to fix, reject, or retry a request.

## Response

A failed request returns an `error` object.

```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"
  }
}
```

## Error fields

| Field | Description |
| - | - |
| `status` | Required HTTP status code returned by the API. |
| `code` | Required machine-readable YCloud error code. |
| `message` | Developer-facing explanation. Do not show it directly to end users. |
| `target` | Request field or resource associated with the error, when available. |
| `docUrl` | Link to more information, when available. |
| `requestId` | Request identifier, also returned in the `YCloud-Request-ID` header, for tracing the request with YCloud support. |
| `whatsappApiError` | Original WhatsApp error details, when a direct WhatsApp API request reaches Meta and fails. |

## Error codes

Use `error.code` to distinguish failures that share an HTTP status. This catalog
lists the YCloud API error codes; an endpoint may document additional errors.

| Code | HTTP status | Meaning and action |
| - | - | - |
| `ACCOUNT_LIMITED` | `403` | An account restriction prevents the action. For example, a trial account can send only to pre-verified numbers. Check the applicable account restrictions. |
| `ACCOUNT_RATE_LIMITED` | `429` | The account quota is exhausted. Pause requests that share the quota and respect `Retry-After`. |
| `ACCOUNT_UNAVAILABLE` | `403` | The account is unavailable. Contact YCloud support. |
| `ALREADY_EXISTS` | `409` | The resource already exists. Check existing resources and request parameters before creating another one. |
| `BAD_REQUEST` | `400` | The request parameters are invalid. Correct the request using the error details. |
| `BALANCE_INSUFFICIENT` | `403` | The account has insufficient balance. Top up before trying again. |
| `CONTENT_PROHIBITED` | `403` | The content violates the service terms. Correct or remove the prohibited content. |
| `CONTENT_TOO_LARGE` | `413` | The request content is too large. Reduce its size. |
| `EMAIL_DOMAIN_UNVERIFIED` | `403` | The email domain is not verified. Complete verification and allow time for it to take effect. |
| `FORBIDDEN` | `403` | You cannot access the resource. Check its ownership and your account permissions. |
| `INTERNAL_SERVER_ERROR` | `500` | YCloud encountered a server error. Retry temporary failures with bounded backoff, subject to the operation’s retry rules. |
| `MESSAGING_REGION_UNSUPPORTED` | `400` | Messaging is not supported for the requested region. Check the destination. |
| `NOT_FOUND` | `404` | The resource does not exist. Check its ID and the endpoint path. |
| `PARAM_INVALID` | `400` | A parameter value is invalid. Correct the field identified in the error details. |
| `PARAM_INVALID_LENGTH` | `400` | A parameter is outside its allowed length. Check the field’s constraints. |
| `PARAM_MISSING` | `400` | A required parameter is missing. Include it in the request. |
| `PARAM_NOT_MATCH` | `400` | Two or more parameters are inconsistent. Check their required relationship. |
| `RECIPIENT_IN_BLOCK_LIST` | `403` | The recipient is blocked. Check the account’s block list before sending. |
| `RECIPIENT_UNSUBSCRIBED` | `403` | The recipient has unsubscribed. Respect the opt-out and check your unsubscribe records. |
| `SENDER_ID_UNAVAILABLE` | `403` | The SMS Sender ID is unregistered or still under review. Check its registration status. |
| `SENDER_RATE_LIMITED` | `429` | The sender quota is exhausted. Slow requests using that sender and respect `Retry-After`. |
| `SERVICE_UNAVAILABLE` | `503` | The service is temporarily unavailable or overloaded. Retry later when safe for the operation. |
| `SMS_SIGNATURE_UNAVAILABLE` | `403` | The signature for Chinese Mainland SMS is unavailable. Check the SMS signature. |
| `TOO_MANY_REQUESTS` | `429` | Requests arrived too quickly. Respect `Retry-After` and reduce traffic with backoff and jitter. |
| `UNAUTHORIZED` | `401` | Authentication failed. Check the API key in `X-API-Key`. |
| `WHATSAPP_PHONE_NUMBER_UNAVAILABLE` | `403` | The WhatsApp phone number is unavailable. Check the sending number. |
| `WHATSAPP_TEMPLATE_UNAVAILABLE` | `403` | The WhatsApp template is missing or is not approved. Check its name and status. |
| `WHATSAPP_WABA_UNAVAILABLE` | `403` | The WhatsApp Business Account is unavailable. Check the WABA ID used by the request. |
| `WHATSAPP_TEMPLATE_UNEDITABLE` | `403` | The template cannot be edited in its current status. Editing requires `APPROVED`, `REJECTED`, or `PAUSED`. |

For account and sender quotas, see [Rate limits](/en/api-reference/guides/api-fundamentals/rate-limits).
Meta errors can also appear in `error.whatsappApiError` after a request reaches
WhatsApp. Preserve those details together with the YCloud error code.

## How to handle the response

| Status | Recommended action |
| - | - |
| `400` | Correct the request parameters or body. |
| `401` | Check the API key. Do not retry unchanged credentials. |
| `403` | Use `error.code` to check the account, balance, recipient, or resource restriction. Correct the cause before retrying. |
| `404` | Check the resource ID and endpoint path. |
| `429` | Respect `Retry-After`, reduce traffic, and use bounded backoff. |
| `5xx` | Retry temporary failures with exponential backoff and jitter. |

## Request correlation

Log the endpoint, HTTP method, response status, YCloud `requestId`, and your own
correlation ID. Remove API keys and personal data. This gives you enough
evidence to investigate a failure without exposing secrets.

## Retry safely

Retry read-only requests when the failure is temporary. Use caution with message sends and other create operations. A repeated `POST` can create a second resource or send a duplicate message.

When supported by the request schema, set `externalId` to a unique value from your system. Store the YCloud response ID after a successful request.

<Tip>
  Include the `requestId`, endpoint, HTTP status, and time of failure when contacting [YCloud support](mailto:service@ycloud.com). Remove API keys and personal data first.
</Tip>

## Implementation checklist

* Parse errors by `code`, not by matching `message` text.
* Set timeouts on every outbound request.
* Retry only temporary failures.
* Add exponential backoff, jitter, and a maximum attempt count.
* Prevent duplicate `POST` effects with your own stable identifier when the
  request supports one.


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