> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia de Errores

> Códigos HTTP, errores de validación comunes y formato de respuesta de error.

## Referencia de Errores

***

## Errores HTTP estándar

| Código                     | Significado                                                           | Acción recomendada                                                                   |
| -------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `400 Bad Request`          | Request malformado o parámetros inválidos.                            | Revisa el campo `detail` de la respuesta — incluye la descripción exacta del error.  |
| `401 Unauthorized`         | API Key ausente o inválida.                                           | Verifica que el header `X-API-Key` esté presente y sea correcto.                     |
| `404 Not Found`            | Cobro no encontrado.                                                  | Verifica que el `external_id` o `charge_id` sea correcto y pertenezca a tu merchant. |
| `422 Unprocessable Entity` | Validación fallida (campo fuera de rango, moneda no soportada, etc.). | Revisa el body de respuesta para el detalle de validación.                           |
| `503 Service Unavailable`  | Proveedor upstream no disponible (temporalmente).                     | Reintenta con backoff exponencial.                                                   |

***

## Errores de validación comunes

| Error                       | Causa                                              | Solución                                                                                                              |
| --------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `unsupported currency: XYZ` | Moneda no soportada.                               | Usa `USDT`, `USDC`, `USD`, `BOB` u otra moneda listada en [criptomonedas soportadas](/payments/crypto/criptomonedas). |
| `amount must be > 0`        | Monto cero o negativo.                             | Verifica que `amount` sea un número positivo.                                                                         |
| `register a webhook first`  | Se llamó `/webhook/test` sin tener URL registrada. | Primero llama a `POST /merchants/me/webhook`.                                                                         |
| `charge not found`          | El cobro no existe o no pertenece al merchant.     | Usa el `external_id` devuelto al crear el cobro.                                                                      |

***

## Formato de error

```json theme={"system"}
{
  "detail": "unsupported currency: XYZ"
}
```

***

## Soporte

Para acceso a producción, configuración de CUCU Direct B2B con Binance, o soporte técnico:

* **Email:** [developers@cucu.ai](mailto:developers@cucu.ai)