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. |
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
{
"detail": "unsupported currency: XYZ"
}