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

# Manejo de errores

> Comprende las respuestas de error de YCloud y reintenta solicitudes de forma segura.

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

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

## 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](/es/api-reference/guides/api-fundamentals/rate-limits).
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.

<Tip>
  Incluya el `requestId`, el endpoint, el estado HTTP y la hora del fallo al contactar con el [soporte de YCloud](mailto:service@ycloud.com). Elimine primero las claves de API y los datos personales.
</Tip>

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


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