Error Response

A request is successfully accepted with an HTTP status code of 2xx. Otherwise, it indicates that something goes wrong with an HTTP status code of 4xx or 5xx. Codes in the 5xx range indicate an error with YCloud's servers, while codes in the 4xx range indicate an error caused by clients.
A structured response body is returned when errors occur, here is an example of the response body for errors:

  "error": {
    "status": 400,
    "code": "PARAM_INVALID",
    "message": "Parameter 'limit' should be between 1 and 100.",
    "target": "limit",
    "docUrl": "",
    "requestId": "req_1KjtKI80IKoaJNa6n6p"

Error Object


REQUIRED. The HTTP status code generated by the server for this occurrence of the problem. It conveys the HTTP status code used for the convenience of the consumer.


REQUIRED. One of the server-defined error codes. Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.


A human-readable representation of the error. It is intended as an aid to developers and is not suitable for exposure to end users.


The target of the error. It could be the parameter field when a parameter is invalid.


A URL to more information about the error.


Each API request has an associated request ID. It conveys the response header YCloud-Request-ID used for the convenience of the consumer. See also Request ID.


The original error object returned by WhatsApp. See Handling Errors, Cloud API Error Codes.

Note: This field is returned if we tried to request Meta WhatsApp API and got an error response. Typically used for the Send a WhatsApp message directly API.

Error Codes

Below is a list of possible error codes, along with additional information about how to resolve them.


HTTP status 403.

Some functions of the account are limited due to some reason. For example, trial accounts can only send messages to pre-verified phone numbers, this error code returns when trial accounts try to send to other phone numbers.


HTTP status 429.

Account-Level rate limit hit. See also Rate Limits.


HTTP status 403.

The account is unavailable. Contact our customer service for more help.


HTTP status 409.

A resource already exists. Please check your owned resources and your request parameters.


HTTP status 400.

Bad Request. Something goes wrong with the request parameters.


HTTP status 403.

The account balance is insufficient. Please top-up.


HTTP status 403.

The content is prohibited according to our terms.


HTTP status 413.

The content is too large. Please reduce the request body.


HTTP status 403.

The email domain is unverified. It may take some minutes to verify the email domain, please wait.


HTTP status 403.

Usually occurs when you try to access a resource that you don't own.


HTTP status 500.

Something goes wrong with our servers. These are rare.


HTTP status 400.

Unsupported region. Typically when you are sending a message to an unsupported region.


HTTP status 404.

The requested resource does not exist.


HTTP status 400.

One or more of the parameters are invalid.


HTTP status 400.

The parameter's length is out of range.


HTTP status 400.

One or more of the parameters are missing.


HTTP status 400.

One parameter does not match with another one.


HTTP status 403.

The recipient has unsubscribed, and will not receive any message you send.

To manage your unsubscribe list, go to Dashboard → Contact → Unsubscribe.


HTTP status 403.

The SMS Sender ID is not registered or is still under review.


HTTP status 429.

Sender-Level rate limit hit. See also Rate Limits.


HTTP status 503.

Temporary due to downtime or due to being overloaded.


HTTP status 403.

The specified signature for Chinese Mainland SMS is not available, please check your signatures.


HTTP status 429.

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. See also Rate Limits.


HTTP status 401.

Unauthorized. It's most likely that you are using the wrong API Key in the X-API-Key header.


HTTP status 403.

The WhatsApp phone number is unavailable. It occurs when you try to send messages using the wrong phone number.


HTTP status 403.

The WhatsApp template is unavailable. It occurs when you try to send template messages when the template does not exist or the template status is not approved.


HTTP status 403.

The WhatsApp business account is unavailable. It occurs when you try to create a template with the wrong WhatsApp business account ID.


HTTP status 403.

The WhatsApp template is uneditable. Templates can only be edited when in an APPROVED, REJECTED, or PAUSED status.