Errores y paginación

Las respuestas exitosas contienen data y meta.requestId. Las respuestas de error contienen error.code, error.message, error.requestId y error.retryable.

En una respuesta 409, el campo opcional error.reason puede indicar la causa específica del conflicto. Si viene duplicate_rfc, ya existe un cliente con ese RFC en la misma cuenta emisora. No esperes este campo en todos los errores 409.

Ejemplo de error

{
  "error": {
    "code": "missing_scope",
    "message": "La API key no tiene permisos para esta operación.",
    "requestId": "identificador-de-la-solicitud",
    "retryable": false
  }
}

El header X-Request-Id también identifica la solicitud. Conserva ese valor al investigar una falla.

Estados HTTP

Estado	Qué revisar
400	JSON, parámetros o validaciones de negocio (por ejemplo INVALID_ISSUE_DATE)
401	Llave ausente, inválida, revocada o de otro ambiente
403	Permisos, plan activo o pago pendiente
404	ID incorrecto, recurso inexistente o de otra cuenta
405	Método no disponible; consulta el header Allow
409	Cliente con RFC duplicado, conflicto de idempotencia o timbrado pendiente
429	Límite de solicitudes; respeta Retry-After
500	Falla interna; conserva el request ID y consulta el documento antes de repetir un timbrado

Ante un 429, espera los segundos indicados por Retry-After. Aplica esperas crecientes con variación aleatoria en tu integración y evita ciclos de reintentos inmediatos. El comportamiento de idempotencia sigue aplicando.

Recorre un listado

Los listados aceptan limit y offset. La respuesta agrega:

Ejemplo de metadatos

{
  "pagination": {
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Este objeto está dentro de meta; data sigue siendo un arreglo. Aumenta offset en limit mientras hasMore sea true.

curl 'https://sandbox.factucat.com/api/v1/invoices?limit=50&offset=50' \
  --header "X-API-Key: $FACTUCAT_API_KEY"

El orden se mantiene por fecha e ID. Las altas concurrentes pueden desplazar páginas cuando se utiliza offset; si sincronizas datos mientras se crean documentos, elimina duplicados por id y vuelve a conciliar el listado.

Métodos y formatos

Las actualizaciones parciales usan PATCH. No hay operaciones PUT en el contrato actual. Las consultas admiten HEAD, y OPTIONS informa los métodos disponibles en Allow.

Los identificadores de clientes, documentos y conceptos en las rutas son UUID. Consulta los límites y filtros específicos en la referencia API.