Respuestas y errores

Éxito y error

{
  "message": "The document was generated successfully",
  "code": 200,
  "cfdi": { "UUID": "6F1A2B3C-4D5E-4F60-8172-93A4B5C6D7E8", "…": "…" }
}

{
  "message": "El CFDI no cumple con el esquema del SAT. Se encontró 1 error de validación. Revisa el campo 'errors' para el detalle.",
  "code": 702,
  "errorType": "cfdi_schema_validation",
  "errors": [
    { "severity": "error", "field": "Rfc", "value": "ZKA010101JWY", "message": "Elemento 'Receptor', campo 'Rfc': …" }
  ]
}

Códigos de la API

Todos están en la matriz de errores con su mensaje exacto, junto a las claves del SAT.

Rechazos del SAT

Cuando el SAT o el proveedor de timbrado rechazan un CFDI, code es 400 y la clave de la matriz del SAT va al inicio de message. Separa la clave del texto con una expresión como ^([A-Za-z]+\d+)\s*-.

{
  "message": "CFDI40143 - Este RFC del receptor no existe en la lista de RFC inscritos no cancelados del SAT.",
  "code": 400
}

El texto que sigue a la clave puede cambiar cuando el SAT actualiza su matriz; la clave no. Un rechazo del SAT no usa folio y se repite igual mientras el dato no cambie.

Respuesta incierta: 5034

Un 5034 dice que la petición llegó al proveedor de timbrado y no volvió una respuesta legible. El CFDI pudo quedar timbrado en el SAT. La respuesta trae la serie y el folio que se usaron y, si se pudo leer, context.uuid.

{
  "message": "El PAC no respondió a tiempo: tu factura pudo haberse timbrado en el SAT aunque no aparezca en tus CFDIs emitidos. Revisa tu buzón o el portal del SAT antes de volver a intentar. Se usó la serie A folio 1001.",
  "code": 5034,
  "Serie": "A",
  "Folio": "1001"
}

1. Si viene context.uuid, el CFDI existe: guárdalo y no lo reenvíes.
2. Si no, búscalo por su serie y folio en tus listados (GET /invoice/listbydaterange) unos minutos después, o en el portal del SAT.
3. Solo si no aparece, reintenta. Si reintentas con la misma Fecha y el mismo Folio que mandaste antes, y el primero sí se timbró, la API responde timbre_previo con su UUID en lugar de duplicarlo.

Uso justo

Cada cuenta tiene 10,000 respuestas de rechazo al día sin costo. Un rechazo es una respuesta 4xx a una petición con llave válida. Los rechazos del SAT por los datos capturados (claves CFDI40xxx) y los 702 por un dato mal formado no cuentan, tampoco lo que piden las pantallas de la propia plataforma.

Si tu integración rebasa el límite, te avisamos antes de cualquier cargo. Con un excedente pendiente se puede activar, a mano, un freno: la API responde HTTP 429 con code 4290 y el encabezado Retry-After a una petición idéntica a otra que ya rechazó en las últimas 24 horas. Las peticiones nuevas o distintas siguen funcionando. Los detalles están en la Política de uso justo de la API.

Formato

• JSON en UTF-8. Manda Accept: application/json o no mandes Accept.
• Las fechas van en hora del centro de México y sin zona: 2026-11-03 10:15:42 o 2026-11-03T10:15:42.
• Los listados regresan los valores de la base como texto: "1160.000000", "1".
• La API se llama de servidor a servidor. Muchos parámetros van en encabezados que un navegador no puede mandar a otro dominio, y la llave nunca debe estar en el navegador.