Errores

La API de Facturación utiliza errores estructurados que te indican exactamente qué salió mal y cómo corregirlo.

Formato de error

{
  "error": {
    "tipo": "error_validacion",
    "codigo": "regimen_fiscal_invalido",
    "mensaje": "El régimen fiscal '601' del cliente no es compatible con el uso de CFDI 'D01'. Usos válidos para el régimen '601': G01, G02, G03.",
    "campo": "cliente.regimen_fiscal",
    "url_doc": "https://docs.facturacion.srs-ngr.com/errores/regimen_fiscal_invalido"
  }
}

Campo	Descripción
`tipo`	Categoría del error
`codigo`	Código de error legible por máquina
`mensaje`	Descripción legible con contexto
`campo`	Qué campo causó el error (si aplica)
`url_doc`	Enlace a la documentación sobre este error

Tipos de error

`tipo`	Estado HTTP	Descripción
`error_validacion`	400	Datos de entrada inválidos
`error_autenticacion`	401	Llave de API faltante o inválida
`no_encontrado`	404	El recurso no existe
`error_conflicto`	409	La operación entra en conflicto con el estado actual
`error_sat`	422	El SAT/PAC rechazó la operación
`error_interno`	500	Error del servidor — reintenta o contacta soporte

Errores comunes

Formato de RFC

codigo: rfc_invalido
mensaje: "El RFC 'INVALIDO' no tiene un formato válido. Debe ser 12 caracteres (persona moral) o 13 caracteres (persona física)."

Uso de CFDI incompatible

codigo: regimen_fiscal_invalido
mensaje: "El régimen fiscal '601' del cliente no es compatible con el uso de CFDI 'D01'."

Factura no timbrable

codigo: estado_invalido
mensaje: "La factura fac_xxx tiene estado 'timbrada'. Solo facturas en estado 'borrador' pueden timbrarse."

UUID de sustitución faltante

codigo: sustitucion_requerida
mensaje: "El motivo de cancelación '01' requiere el UUID del CFDI de sustitución en el campo 'uuid_sustitucion'."

CSD vencido

codigo: certificado_vencido
mensaje: "El certificado cert_xxx venció el 2025-12-31. Renueve su CSD en el portal del SAT."

Errores de idempotencia

Si envías una solicitud con un encabezado Clave-Idempotencia que ya fue utilizado con un cuerpo de solicitud diferente:

{
  "error": {
    "tipo": "error_conflicto",
    "codigo": "clave_idempotencia_duplicada",
    "mensaje": "La clave de idempotencia 'pedido_12345' ya fue utilizada con un cuerpo de solicitud diferente."
  }
}

Webhooks