Error Reference
Known Cobru error patterns, misleading status codes, and troubleshooting guidance.
Cobru's current error model is functional but not yet ergonomic. Some validation failures show up as 403 Forbidden, and the response shape is not consistently descriptive.
Current response formats
You will most often see one of these:
{ "error": "Error en la creacion del cobru." }{ "payment_method_enabled": ["Not a valid string."] }Error-handling strategy
Capture the exact HTTP status, headers, and raw response body from Cobru.
Normalize Cobru's response into your own internal error type.
Decide whether the error is retryable, fixable by the caller, or operational.
Surface a safe customer-facing message while keeping the raw Cobru payload in logs.
Known quirks
| Symptom | HTTP code | Actual cause | Fix |
|---|---|---|---|
payment_method_enabled sent as object | 400 | Cobru expects a JSON string | JSON.stringify() before sending |
Missing payer_redirect_url or callback | 403 | request validation failure | send both fields on payment creation |
| Credentials are present but create payment still fails | 403 | body shape may be invalid, not auth | verify payment_method_enabled, redirect URLs, and content type |
refresh_token body field fails | 400 or auth failure | wrong field name | use refresh |
| Payment URL does not open | client bug | using pk path instead of url slug | build {baseUrl}/{url} |
Suggested internal error categories
| Category | Use for |
|---|---|
configuration_error | missing credentials, wrong environment, missing callback URL |
request_validation_error | malformed payloads, wrong field types, missing required fields |
authentication_error | invalid or expired auth material |
provider_processing_error | Cobru or downstream payment provider failed after request validation |
reconciliation_error | callback and payment status do not match your internal order state |
Troubleshooting checklist
- Confirm you are hitting the right base URL.
- Confirm all three credentials are present.
- Log the exact JSON body before sending.
- Verify
payment_method_enabledis serialized as a string. - Confirm
callbackandpayer_redirect_urlare valid HTTPS URLs. - Keep raw responses from Cobru in logs during integration.
What to log for every failed request
- internal request ID
- Cobru endpoint and method
- sanitized request body
- HTTP status
- raw Cobru response
- internal error category
- retry decision
Retry guidance
Desired future model
A future Cobru error model should move to application/problem+json with stable machine-readable error types. Until then, your integration should normalize Cobru responses into your own internal error format.