Errores y rate limits

Cada API usa un envelope distinto. Conserva requestId y los headers de rate limit al registrar un incidente.

API de integraciones

{
  "error": {
    "code": "invalid_signature",
    "message": "The request signature is invalid.",
    "requestId": "req-1001"
  }
}

HTTP	Códigos frecuentes	Acción
`400`	`missing_idempotency_key`	Agrega `Idempotency-Key` a todo `POST`.
`401`	`invalid_api_key`, `revoked_api_key`, `expired_api_key`	Comprueba o rota la llave.
`401`	`missing_signature`, `missing_timestamp`, `invalid_signature`, `timestamp_out_of_tolerance`	Reconstruye la firma con el cuerpo exacto.
`403`	`company_mismatch`, `insufficient_scope`	Corrige empresa o scopes.
`404`	Recurso externo no encontrado	Verifica `source` e identificador externo.
`409`	Conflicto de idempotencia o estado	No repitas con otro payload; consulta el recurso.
`422`	Regla financiera o selección inválida	Corrige moneda, cliente o documentos.
`429`	`rate_limited`	Aplica backoff.

El límite normal es 120 solicitudes por minuto por llave y ruta. verified-payments usa 60 por minuto.

API pública de documentos de cobro

{
  "message": "La solicitud contiene errores de validación.",
  "code": 10001,
  "code_name": "validation_error",
  "errors": {
    "amount": ["El monto debe ser al menos 0.01."]
  }
}

HTTP	`code_name`	Uso
`401`	`authentication_error`	Bearer ausente o inválido.
`403`	`forbidden`	Scope faltante o compañía no habilitada.
`404`	`not_found`	Documento inexistente o de otra empresa.
`409`	`idempotency_error`	Clave ausente o reutilizada con otro cuerpo.
`409`	`conflict`	Pago aplicado, monto pagado, estado terminal o actualización pendiente.
`422`	`validation_error`	Campo inválido, ausente o no permitido.
`429`	`rate_limit_error`	Límite distribuido excedido.
`500`	`INTERNAL_ERROR`	Error interno sanitizado; contacta soporte.
`503`	`service_unavailable`	Ledger o configuración financiera no disponible.

La API incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. En 429, respeta Retry-After.

Estrategia de reintento

Reintenta timeouts, 429 y 5xx con backoff exponencial y jitter.
Conserva la misma clave de idempotencia y el mismo payload.
No reintentes automáticamente 401, 403, 404 o 422 sin corregir la causa.
Ante un 409, consulta el recurso antes de iniciar una operación nueva.
Registra método, ruta, status, requestId, código y clave de idempotencia; nunca registres el Bearer o firmas.

Comenzar

Seguridad y operación

Recursos

Errores y rate limits

API de integraciones

API pública de documentos de cobro

Estrategia de reintento

​API de integraciones

​API pública de documentos de cobro

​Estrategia de reintento

API de integraciones

API pública de documentos de cobro

Estrategia de reintento