Handle errors

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.

{
  "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. 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.

Include the requestId, endpoint, HTTP status, and time of failure when contacting YCloud support. Remove API keys and personal data first.

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.

Getting Started

Guides

Endpoints

Webhooks

What it is

Response

Error fields

Error codes

How to handle the response

Request correlation

Retry safely

Implementation checklist

​What it is

​Response

​Error fields

​Error codes

​How to handle the response

​Request correlation

​Retry safely

​Implementation checklist

What it is

Response

Error fields

Error codes

How to handle the response

Request correlation

Retry safely

Implementation checklist