Documentation Index
Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt
Use this file to discover all available pages before exploring further.
{
"statusCode": 400,
"message": "Customer email must be a valid email",
"error": "Bad Request",
"timestamp": "2026-03-26T14:30:00.000Z",
"path": "/api/external/payments"
}
| Campo | Descripción |
|---|
statusCode | Código HTTP |
message | Mensaje legible con el detalle del fallo |
error | Nombre del error HTTP |
timestamp | Fecha ISO 8601 del error |
path | Endpoint que produjo el error |
Códigos HTTP
| Código | Significado | Cuándo |
|---|
200 | OK | GET, DELETE (cancel) |
201 | Created | POST (nuevo pago/key) |
204 | No Content | DELETE (revocar key) |
400 | Bad Request | Error de validación, cliente inactivo |
401 | Unauthorized | API key faltante, inválida o revocada |
403 | Forbidden | IP no está en la allowlist |
404 | Not Found | Pago o key no encontrado |
409 | Conflict | Idempotency-Key duplicada, máximo de keys, pago no cancelable |
429 | Too Many Requests | Rate limit excedido |
500 | Server Error | Error inesperado |
Errores comunes
| Mensaje | Causa | Solución |
|---|
"Client is not active" | El cliente no tiene estado activo | Contactar soporte — datos legacy |
"Idempotency-Key header is required" | Falta el header en un POST | Agregar Idempotency-Key con UUID v4 |
"Customer has no pending invoices" | Problema de generación de factura | Verifica amountMinor y currency |
"Company has reached the maximum number of active sessions" | Demasiados pagos hosted activos | Cancela pagos pendientes o espera a que expiren |
"Invalid or revoked API key" | Key mal copiada, expirada o revocada | Regenera la key desde el dashboard |
"Payment is not cancelable" | El pago no está en pending | Solo pending se puede cancelar |
Rate limiting
Cada API key tiene un límite por defecto de 60 requests/minuto.
{
"statusCode": 429,
"message": "Rate limit exceeded (60 requests/minute)"
}
Estrategia de reintento
- Espera 1 segundo tras el primer
429.
- Backoff exponencial: 1s, 2s, 4s, 8s…
- Máximo 3 reintentos antes de alertar.
- Siempre reintenta con la misma
Idempotency-Key.
async function withRetry(fn, { maxRetries = 3 } = {}) {
let delay = 1000
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
return await fn()
} catch (error) {
const status = error.response?.status ?? error.status
if (status !== 429 || attempt === maxRetries) throw error
await new Promise((r) => setTimeout(r, delay))
delay *= 2
}
}
}
Manejo genérico
async function cobrixCall(fn) {
try {
return await fn()
} catch (error) {
const { statusCode, message } = error.body ?? {}
switch (statusCode) {
case 401:
throw new Error('API key inválida o revocada')
case 404:
return null
case 409:
throw new Error(`Conflicto: ${message}`)
case 429:
// usa withRetry en lugar de lanzar
throw error
case 500:
case 502:
case 503:
// reintenta tras unos segundos
throw error
default:
throw error
}
}
}
timestamp y path del errorstatusCode y message- Endpoint y body (sin datos sensibles)
- Ambiente (Staging / Producción)
