Errors

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": "https://example.com/errors#param_invalid",
    "requestId": "req_1KjtKI80IKoaJNa6n6p"
  }
}

Error Object

status

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.

code

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.

message

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

target

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

docUrl

A URL to more information about the error.

requestId

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.

whatsappApiError

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.

ACCOUNT_LIMITED

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.

ACCOUNT_RATE_LIMITED

HTTP status 429.

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

ACCOUNT_UNAVAILABLE

HTTP status 403.

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

ALREADY_EXISTS

HTTP status 409.

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

BAD_REQUEST

HTTP status 400.

Bad Request. Something goes wrong with the request parameters.

BALANCE_INSUFFICIENT

HTTP status 403.

The account balance is insufficient. Please top-up.

CONTENT_PROHIBITED

HTTP status 403.

The content is prohibited according to our terms.

CONTENT_TOO_LARGE

HTTP status 413.

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

EMAIL_DOMAIN_UNVERIFIED

HTTP status 403.

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

FORBIDDEN

HTTP status 403.

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

INTERNAL_SERVER_ERROR

HTTP status 500.

Something goes wrong with our servers. These are rare.

MESSAGING_REGION_UNSUPPORTED

HTTP status 400.

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

NOT_FOUND

HTTP status 404.

The requested resource does not exist.

PARAM_INVALID

HTTP status 400.

One or more of the parameters are invalid.

PARAM_INVALID_LENGTH

HTTP status 400.

The parameter's length is out of range.

PARAM_MISSING

HTTP status 400.

One or more of the parameters are missing.

PARAM_NOT_MATCH

HTTP status 400.

One parameter does not match with another one.

RECIPIENT_IN_BLOCK_LIST

HTTP status 403.

Messages cannot be sent because the recipient is in your block list.

RECIPIENT_UNSUBSCRIBED

HTTP status 403.

Messages cannot be sent because the recipient has unsubscribed.

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

SENDER_ID_UNAVAILABLE

HTTP status 403.

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

SENDER_RATE_LIMITED

HTTP status 429.

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

SERVICE_UNAVAILABLE

HTTP status 503.

Temporary due to downtime or due to being overloaded.

SMS_SIGNATURE_UNAVAILABLE

HTTP status 403.

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

TOO_MANY_REQUESTS

HTTP status 429.

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

UNAUTHORIZED

HTTP status 401.

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

WHATSAPP_PHONE_NUMBER_UNAVAILABLE

HTTP status 403.

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

WHATSAPP_TEMPLATE_UNAVAILABLE

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.

WHATSAPP_WABA_UNAVAILABLE

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.

WHATSAPP_TEMPLATE_UNEDITABLE

HTTP status 403.

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