Referencia de errores
Patrones de error conocidos en Cobru, status codes engañosos y guía de troubleshooting.
El modelo actual de errores de Cobru funciona, pero todavía no es ergonómico. Algunas fallas de validación aparecen como 403 Forbidden, y la forma de la respuesta no siempre es descriptiva.
Formatos de respuesta actuales
Lo más común es ver una de estas respuestas:
{ "error": "Error en la creacion del cobru." }{ "payment_method_enabled": ["Not a valid string."] }Estrategia recomendada para manejar errores
Captura el status HTTP exacto, headers y body raw de respuesta de Cobru.
Normaliza la respuesta de Cobru a tu propio tipo de error interno.
Decide si el error es reintentable, corregible por el caller u operativo.
Muestra un mensaje seguro al usuario final y conserva el payload raw en logs.
Quirks conocidos
| Síntoma | HTTP code | Causa real | Fix |
|---|---|---|---|
payment_method_enabled enviado como objeto | 400 | Cobru espera un string JSON | ejecutar JSON.stringify() antes de enviar |
falta payer_redirect_url o callback | 403 | falla de validación del request | enviar ambos campos al crear el pago |
| hay credenciales pero falla la creación del pago | 403 | la forma del body puede ser inválida, no auth | revisar payment_method_enabled, redirect URLs y content type |
falla el campo refresh_token | 400 o auth failure | nombre de campo incorrecto | usar refresh |
| la URL de pago no abre | bug cliente | se está usando pk en vez del slug url | construir {baseUrl}/{url} |
Categorías internas sugeridas
| Categoría | Úsala para |
|---|---|
configuration_error | credenciales faltantes, ambiente incorrecto, callback URL ausente |
request_validation_error | payloads mal formados, tipos inválidos, campos requeridos ausentes |
authentication_error | material de auth inválido o expirado |
provider_processing_error | Cobru o un proveedor downstream falló después de validar el request |
reconciliation_error | el callback y el estado del pago no coinciden con tu estado interno |
Checklist de troubleshooting
- Confirma que estás usando la base URL correcta.
- Confirma que las tres credenciales están presentes.
- Loguea el JSON exacto antes de enviarlo.
- Verifica que
payment_method_enabledvaya serializado como string. - Confirma que
callbackypayer_redirect_urlsean URLs HTTPS válidas. - Conserva las respuestas raw de Cobru en logs durante la integración.
Qué conviene loguear en cada request fallido
- request ID interno
- endpoint y método Cobru
- body sanitizado enviado
- status HTTP
- respuesta raw de Cobru
- categoría interna del error
- decisión de retry
Guía de reintentos
Modelo deseable a futuro
Un modelo futuro de errores en Cobru debería migrar a application/problem+json con tipos de error estables y legibles por máquina. Hasta entonces, conviene normalizar las respuestas de Cobru a tu propio formato interno.