> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timbrix.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# Glosario de errores SAT

> Causas y soluciones de los errores CFDI##### más comunes al timbrar con Timbrix, y cómo se ven en cada canal (API REST, SDK, MCP).

<Tip>Tiempo de lectura: \~3 minutos.</Tip>

Cuando el PAC rechaza un CFDI, el error trae embebido un código de
catálogo del SAT con el formato `CFDI#####`. Esta página documenta los
códigos que Timbrix ha visto y verificado en producción/sandbox, con su
causa real y su solución. No es un catálogo exhaustivo del Anexo 20 del
SAT — el catálogo oficial de errores de validación tiene un rango mucho
más amplio de códigos; aquí solo documentamos los que Timbrix confirma
consistentemente en su integración con el PAC.

## Cómo se ve el error en cada canal

El PAC **siempre** responde el error como texto libre, nunca como un
`{code, message}` estructurado. El código `CFDI#####` viene embebido
dentro de ese texto (ej. `"Error timbrado: CFDI40143 - Este RFC del
receptor no existe..."`), y cada canal de Timbrix te lo entrega dentro de
ese mismo texto libre:

| Canal                    | Dónde aparece el texto libre                                                       |
| ------------------------ | ---------------------------------------------------------------------------------- |
| **API REST directa**     | Campo `error` del body de respuesta (status `422` para errores de negocio SAT/PAC) |
| **SDK (`@timbrix/sdk`)** | `error.message` de la instancia `TimbrixApiError` lanzada por la petición fallida  |
| **MCP (`@timbrix/mcp`)** | `result.content[0].text` cuando `result.isError` es `true`                         |

En los tres casos, el patrón para extraer el código es el mismo:
buscar `/\bCFDI\d{4,6}\b/` dentro del texto. Timbrix nunca separa este
código a un campo estructurado aparte — trátalo siempre como texto libre
que puede incluir contexto adicional del PAC.

## CFDI40130 — Falta `InformacionGlobal`

**Causa:** El CFDI es de tipo Ingreso para "público en general"
(`receptor.rfc = XAXX010101000`, `receptor.nombre = PUBLICO EN GENERAL`)
pero no incluye el nodo `InformacionGlobal` (periodicidad, meses, año),
que el SAT exige en ese caso.

**Solución:** Agrega `InformacionGlobal.Periodicidad`,
`InformacionGlobal.Meses` e `InformacionGlobal.Año` al timbrar, y asegúrate
de que `receptor.UsoCFDI` sea `S01`.

**Ejemplo del texto libre:**

```text theme={null}
Error timbrado: CFDI40130 - El campo InformacionGlobal es requerido cuando
el receptor es el RFC generico XAXX010101000
```

## CFDI40143 — RFC del receptor no inscrito

**Causa:** El RFC del receptor no está inscrito o vigente ante el SAT. Es
el error más común en sandbox, donde es fácil usar un RFC inventado.

**Solución:** Usa `XAXX010101000` (público en general) para pruebas, o un
RFC real y vigente en producción.

**Ejemplo del texto libre:**

```text theme={null}
Error timbrado: CFDI40143 - Este RFC del receptor no existe en la lista
de RFC inscritos no cancelados del SAT.
```

## CFDI40102 — puede ser un falso positivo

**Causa aparente:** El mensaje dice que "el resultado de la digestión debe
ser igual al resultado de la desencripción del sello", lo que parece un
problema con tu CSD (certificado de sello digital).

**Causa real, con más frecuencia:** El PAC internamente reintenta varias
variantes de formato de certificado antes de fallar, pero siempre reporta
el error de la primera variante como resultado final — incluso cuando la
causa real es otra. Las dos causas reales más comunes detrás de un
`CFDI40102` son:

* **`date` enviado en UTC en vez de hora de Ciudad de México.** El PAC
  compara la fecha de expedición contra su propio reloj en hora de México
  sin ninguna conversión; un valor en UTC se ve \~6 horas en el futuro y
  cae fuera de la ventana de 72 horas que exige el SAT.
* **RFC del receptor no inscrito** — la misma causa que `CFDI40143`.

**Solución:** Antes de asumir que tu CSD está mal, revisa primero que
`date` esté en hora de México (`America/Mexico_City`, sin zona horaria en
el string) y que el RFC del receptor sea válido. Solo si ambos son
correctos y el error persiste, investiga el par `.cer`/`.key` de tu CSD.

**Ejemplo del texto libre:**

```text theme={null}
Error timbrado: CFDI40102 - El resultado de la digestión debe ser igual
al resultado de la desencripción del sello.
```

<Warning>
  Este es el error más engañoso de los tres: su mensaje apunta a un problema de
  certificado, pero en la mayoría de los casos reales confirmados por Timbrix la
  causa era la zona horaria de `date` o un RFC de receptor no inscrito — no el
  CSD.
</Warning>

## Nota sobre el catálogo completo de errores del SAT

El Anexo 20 del SAT define un catálogo de validación mucho más amplio que
los tres códigos anteriores, cubriendo cada regla estructural del XML
CFDI 4.0. Esta página no intenta ser ese catálogo completo — solo
documenta los códigos que Timbrix ha confirmado y verificado en su propia
integración con el PAC. Si te encuentras con un código `CFDI#####` que no
aparece aquí, revisa el texto completo del mensaje (suele incluir una
descripción legible del campo o regla que falló) y, si el problema
persiste, contacta a soporte con el UUID o el payload usado.

<CardGroup cols={2}>
  <Card title="Glosario fiscal" icon="book" href="/glossary">
    Términos como CFDI, RFC, PAC y CSD explicados.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Endpoints, autenticación y límites de tasa.
  </Card>
</CardGroup>