Errores

Todas las respuestas de error de la API de FactuLink siguen un formato consistente para facilitar el manejo programático. Esta página describe la estructura de errores, los códigos HTTP que puedes recibir y los errores más comunes al trabajar con CFDIs.

Formato estándar de error

Cuando una petición falla, la API responde con un JSON que contiene tres campos principales:


{
  "error": {
    "code": "HTTP_400",
    "message": "Descripción legible del error",
    "details": [
      { "field": "receptor.rfc", "issue": "RFC con formato inválido" }
    ]
  },
  "path": "/api/v1/cfdis",
  "timestamp": "2026-04-05T12:00:00Z"
}

Campo	Tipo	Descripción
`error.code`	`string`	Código único del error (e.g. `HTTP_400`, `PAC_REJECTION`)
`error.message`	`string`	Descripción legible para desarrolladores
`error.details`	`array`	Lista de errores específicos por campo (opcional)
`path`	`string`	Endpoint que generó el error
`timestamp`	`string`	Fecha/hora UTC del error en formato ISO 8601

Códigos de estado HTTP

Código	Nombre	Descripción
400	Bad Request	Datos de entrada inválidos o faltantes. Revisa `error.details` para ver qué campos tienen problema.
401	Unauthorized	No se envió token de autenticación o el token es inválido/expirado.
403	Forbidden	El token es válido pero no tiene permisos (scopes) suficientes para esta operación.
404	Not Found	El recurso solicitado no existe. Verifica el ID o la ruta del endpoint.
422	Unprocessable Entity	Los datos son válidos en formato pero fueron rechazados por el PAC o el SAT. Revisa `error.details`.
429	Too Many Requests	Excediste el límite de peticiones por minuto. Consulta la página de Rate Limits.
500	Internal Server Error	Error interno del servidor. Si persiste, contacta soporte.
502	Bad Gateway	No se pudo conectar con un servicio externo (PAC, SAT). Reintenta en unos segundos.
503	Service Unavailable	El PAC o un servicio dependiente no está disponible temporalmente. Reintenta con backoff.

Errores comunes de CFDI

Estos son los errores más frecuentes al crear o timbrar CFDIs:

RFC inválido

El RFC del emisor o receptor no cumple el formato del SAT (12 caracteres para persona moral, 13 para persona física).

POST/api/v1/cfdis400

Request

{
"receptor": {
  "rfc": "INVALIDO",
  "nombre": "Juan Pérez",
  "regimen_fiscal": "601",
  "domicilio_fiscal": "06600",
  "uso_cfdi": "G03"
}
}

Response

{
"error": {
  "code": "HTTP_400",
  "message": "Error de validación en los datos del CFDI",
  "details": [
    {
      "field": "receptor.rfc",
      "issue": "RFC con formato inválido. Debe tener 12 caracteres (persona moral) o 13 (persona física)."
    }
  ]
},
"path": "/api/v1/cfdis",
"timestamp": "2026-04-05T12:00:00Z"
}

CSD vencido

El Certificado de Sello Digital (CSD) del emisor ha expirado. Debes renovar el CSD ante el SAT y subirlo nuevamente.

Concepto sin impuestos cuando ObjetoImp = “02”

Cuando un concepto tiene objeto_imp: "02" (Sí objeto de impuesto), es obligatorio incluir al menos un traslado o retención de impuestos en ese concepto. El PAC rechazará el CFDI si falta la sección de impuestos.

Serie/Folio duplicado

La combinación de serie y folio ya fue utilizada en un CFDI previo. Cada CFDI debe tener una combinación única de serie + folio.

Ejemplo: Rechazo del PAC (422)

POST/api/v1/cfdis422

Request

{
"serie": "A",
"conceptos": [
  {
    "clave_prod_serv": "84111506",
    "cantidad": 1,
    "clave_unidad": "E48",
    "descripcion": "Consultoría",
    "valor_unitario": 10000,
    "objeto_imp": "02",
    "impuestos": {}
  }
]
}

Response

{
"error": {
  "code": "PAC_REJECTION",
  "message": "El CFDI fue rechazado por el PAC",
  "details": [
    {
      "field": "conceptos[0].impuestos",
      "issue": "El concepto tiene ObjetoImp='02' pero no incluye traslados ni retenciones de impuestos."
    }
  ]
},
"path": "/api/v1/cfdis",
"timestamp": "2026-04-05T12:00:00Z"
}

Buenas prácticas para manejo de errores

Siempre revisa error.details. Contiene información específica por campo que te permite mostrar mensajes útiles al usuario o corregir la petición programáticamente.
Diferencia entre 400 y 422. Un 400 significa que los datos no pasaron la validación local (formato, campos requeridos). Un 422 significa que el PAC o SAT rechazó el CFDI después de validarlo.
Implementa reintentos para 502 y 503. Estos errores suelen ser temporales. Usa exponential backoff con un máximo de 3 reintentos.
No reintentes errores 400, 401 o 403. Estos requieren corrección en la petición o en la configuración de autenticación.
Loguea el timestamp y path. Son útiles para abrir tickets de soporte y correlacionar con logs del servidor.