Manejo de errores

Qué es

YCloud utiliza códigos de estado HTTP y un cuerpo de error estructurado para que tu aplicación pueda decidir si corregir, rechazar o reintentar una solicitud.

Respuesta

Una solicitud fallida devuelve un objeto error.

{
  "error": {
    "status": 404,
    "code": "NOT_FOUND",
    "message": "The requested resource does not exist.",
    "requestId": "req_1KjtKI80IKoaJNa6n6p"
  }
}

Campos de error

Campo	Descripción
`status`	Código de estado HTTP obligatorio devuelto por la API.
`code`	Código de error legible por máquina obligatorio de YCloud.
`message`	Explicación para desarrolladores. No la muestres directamente a los usuarios finales.
`target`	Campo de solicitud o recurso asociado con el error, cuando esté disponible.
`docUrl`	Enlace a más información, cuando esté disponible.
`requestId`	Identificador de la solicitud, también devuelto en el encabezado `YCloud-Request-ID`, para rastrear la solicitud con el soporte de YCloud.
`whatsappApiError`	Detalles del error original de WhatsApp, cuando una solicitud directa a la API de WhatsApp llega a Meta y falla.

Códigos de error

Utiliza error.code para distinguir fallos que comparten un mismo estado HTTP. Este catálogo enumera los códigos de error de la API de YCloud; un endpoint puede documentar errores adicionales.

Código	Estado HTTP	Significado y acción
`ACCOUNT_LIMITED`	`403`	Una restricción de la cuenta impide la acción. Por ejemplo, una cuenta de prueba solo puede enviar a números previamente verificados. Revisa las restricciones aplicables de la cuenta.
`ACCOUNT_RATE_LIMITED`	`429`	Se agotó la cuota de la cuenta. Pausa las solicitudes que comparten la cuota y respeta `Retry-After`.
`ACCOUNT_UNAVAILABLE`	`403`	La cuenta no está disponible. Ponte en contacto con el soporte de YCloud.
`ALREADY_EXISTS`	`409`	El recurso ya existe. Comprueba los recursos existentes y los parámetros de la solicitud antes de crear otro.
`BAD_REQUEST`	`400`	Los parámetros de la solicitud no son válidos. Corrige la solicitud utilizando los detalles del error.
`BALANCE_INSUFFICIENT`	`403`	La cuenta no tiene saldo suficiente. Recarga antes de intentar de nuevo.
`CONTENT_PROHIBITED`	`403`	El contenido infringe los términos del servicio. Corrige o elimina el contenido prohibido.
`CONTENT_TOO_LARGE`	`413`	El contenido de la solicitud es demasiado grande. Reduce su tamaño.
`EMAIL_DOMAIN_UNVERIFIED`	`403`	El dominio de correo electrónico no está verificado. Completa la verificación y espera a que surta efecto.
`FORBIDDEN`	`403`	No puedes acceder al recurso. Comprueba su propiedad y los permisos de tu cuenta.
`INTERNAL_SERVER_ERROR`	`500`	YCloud experimentó un error de servidor. Reintenta los fallos temporales con un retroceso limitado (backoff), sujeto a las reglas de reintento de la operación.
`MESSAGING_REGION_UNSUPPORTED`	`400`	No se admite el envío de mensajes para la región solicitada. Comprueba el destino.
`NOT_FOUND`	`404`	El recurso no existe. Comprueba su ID y la ruta del endpoint.
`PARAM_INVALID`	`400`	El valor de un parámetro no es válido. Corrige el campo identificado en los detalles del error.
`PARAM_INVALID_LENGTH`	`400`	Un parámetro excede o no alcanza la longitud permitida. Comprueba las restricciones del campo.
`PARAM_MISSING`	`400`	Falta un parámetro obligatorio. Inclúyelo en la solicitud.
`PARAM_NOT_MATCH`	`400`	Dos o más parámetros son inconsistentes. Comprueba la relación requerida entre ellos.
`RECIPIENT_IN_BLOCK_LIST`	`403`	El destinatario está bloqueado. Consulta la lista de bloqueo de la cuenta antes de enviar.
`RECIPIENT_UNSUBSCRIBED`	`403`	El destinatario canceló la suscripción. Respeta la baja voluntaria y revisa tus registros de cancelaciones de suscripción.
`SENDER_ID_UNAVAILABLE`	`403`	El Sender ID de SMS no está registrado o aún se encuentra en revisión. Comprueba el estado de su registro.
`SENDER_RATE_LIMITED`	`429`	Se agotó la cuota del remitente. Reduce el ritmo de las solicitudes que utilizan ese remitente y respeta `Retry-After`.
`SERVICE_UNAVAILABLE`	`503`	El servicio no está disponible temporalmente o está sobrecargado. Reintente más tarde cuando sea seguro para la operación.
`SMS_SIGNATURE_UNAVAILABLE`	`403`	La firma para SMS de China continental no está disponible. Compruebe la firma de SMS.
`TOO_MANY_REQUESTS`	`429`	Las solicitudes llegaron con demasiada rapidez. Respete `Retry-After` y reduzca el tráfico con retroceso (backoff) y variación aleatoria (jitter).
`UNAUTHORIZED`	`401`	Error de autenticación. Compruebe la clave de API en `X-API-Key`.
`WHATSAPP_PHONE_NUMBER_UNAVAILABLE`	`403`	El número de teléfono de WhatsApp no está disponible. Compruebe el número de envío.
`WHATSAPP_TEMPLATE_UNAVAILABLE`	`403`	La plantilla de WhatsApp no existe o no está aprobada. Compruebe su nombre y estado.
`WHATSAPP_WABA_UNAVAILABLE`	`403`	La cuenta de WhatsApp Business no está disponible. Compruebe el ID de WABA utilizado en la solicitud.
`WHATSAPP_TEMPLATE_UNEDITABLE`	`403`	La plantilla no se puede editar en su estado actual. La edición requiere `APPROVED`, `REJECTED` o `PAUSED`.

Para consultar las cuotas de cuenta y remitente, consulte Límites de frecuencia. Los errores de Meta también pueden aparecer en error.whatsappApiError después de que una solicitud llegue a WhatsApp. Conserve esos detalles junto con el código de error de YCloud.

Cómo manejar la respuesta

Estado	Acción recomendada
`400`	Corrija los parámetros o el cuerpo de la solicitud.
`401`	Compruebe la clave de API. No reintente con credenciales sin modificar.
`403`	Use `error.code` para comprobar la restricción de cuenta, saldo, destinatario o recurso. Corrija la causa antes de reintentar.
`404`	Compruebe el ID del recurso y la ruta del endpoint.
`429`	Respete `Retry-After`, reduzca el tráfico y utilice un retroceso delimitado.
`5xx`	Reintente los errores temporales con retroceso exponencial y variación aleatoria (jitter).

Correlación de solicitudes

Registre en los logs el endpoint, el método HTTP, el estado de la respuesta, el requestId de YCloud y su propio ID de correlación. Elimine las claves de API y los datos personales. Esto le proporciona suficiente evidencia para investigar un fallo sin exponer información confidencial.

Reintentar de forma segura

Reintente las solicitudes de solo lectura cuando el fallo sea temporal. Tenga precaución con los envíos de mensajes y otras operaciones de creación. Un POST repetido puede crear un segundo recurso o enviar un mensaje duplicado. Cuando el esquema de la solicitud lo admita, establezca externalId en un valor único de su sistema. Almacene el ID de respuesta de YCloud tras una solicitud correcta.

Incluya el requestId, el endpoint, el estado HTTP y la hora del fallo al contactar con el soporte de YCloud. Elimine primero las claves de API y los datos personales.

Lista de verificación de implementación

Analice los errores mediante code, no mediante la coincidencia del texto de message.
Configure tiempos de espera en cada solicitud saliente.
Reintente únicamente los fallos temporales.
Añada retroceso exponencial, variación aleatoria (jitter) y un límite máximo de intentos.
Evite efectos secundarios de POST duplicados con su propio identificador estable cuando la solicitud lo admita.

Primeros pasos

Guías

Endpoints

Webhooks

Qué es

Respuesta

Campos de error

Códigos de error

Cómo manejar la respuesta

Correlación de solicitudes

Reintentar de forma segura

Lista de verificación de implementación

​Qué es

​Respuesta

​Campos de error

​Códigos de error

​Cómo manejar la respuesta

​Correlación de solicitudes

​Reintentar de forma segura

​Lista de verificación de implementación

Qué es

Respuesta

Campos de error

Códigos de error

Cómo manejar la respuesta

Correlación de solicitudes

Reintentar de forma segura

Lista de verificación de implementación