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.

Error	Causa	Solución
`unsupported currency: XYZ`	Moneda no soportada.	Usa `USDT`, `USDC`, `USD`, `BOB` u otra moneda listada en criptomonedas soportadas.
`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.

{
  "detail": "unsupported currency: XYZ"
}

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