Documentación de la API · v1

Errores y reintentos de la API

Qué significa cada código HTTP de la API de timbrado, cuándo reintentar, cómo usar Idempotency-Key para no timbrar dos veces y qué hacer con cada estado.

Todo error de la API regresa { "ok": false, "error": "..." }. Los que vienen del PAC (502) traen además codigo y detalle con la razón real del rechazo.

Códigos HTTP y qué hacer con cada uno

CódigoSignificado¿Reintentar?Qué hacer
400Datos inválidosNoLee error, que dice exactamente qué campo falló, y corrige el body.
401API key inválida o expiradaNoRevisa el header X-Api-Key; si era de sandbox y expiró, regenérala.
402Sin timbres disponiblesNoCompra o recarga timbres desde el portal.
403Sin acceso a la APINoContrata el módulo de API, o certifica tu cuenta si usabas la key de producción.
404Recurso inexistenteNoRevisa el id y que corresponda al mismo ambiente que tu key.
409Operación concurrente sobre el mismo documentoSí, tras unos segundosEspera y consulta GET /:id para ver en qué quedó.
429Límite de peticiones excedidoSí, con esperaUsa RateLimit-Reset para calcular cuánto esperar.
502El PAC rechazó el CFDI o la cancelaciónSí, con la misma Idempotency-KeyLee codigo y detalle para saber qué corregir.

Reintentos seguros con Idempotency-Key

Para reintentar sin timbrar dos veces (por ejemplo, tras un timeout de red), manda el header Idempotency-Key con un texto único de hasta 255 caracteres. Si ya existe un comprobante tuyo con esa clave, el servidor regresa el original en lugar de timbrar y cobrar otra vez. Aplica a los endpoints de creación: /facturas, /facturas/:id/nota-credito, /complementos-pago, /nomina y /retenciones.

curl

curl -X POST https://app.timbra-mx.com/api/v1/facturas \
  -H "X-Api-Key: TU_API_KEY" \
  -H "Idempotency-Key: pedido-84231-intento-1" \
  -H "Content-Type: application/json" \
  -d '{ "xml": "..." }'

Lo que conviene saber de la idempotencia:

Estados de un comprobante

EstadoSignificadoQué hacer
timbrandoPetición en curso hacia el PAC; es transitorio.Si lo ves en un GET, espera unos segundos y consulta de nuevo.
timbradaCFDI válido, con uuidFiscal y xml.Guarda id y uuidFiscal; ya puedes descargar /xml y /pdf.
errorEl PAC rechazó el timbrado.Revisa errorCodigo y errorMensaje en GET /:id, corrige el dato y manda un POST nuevo.
cancelandoSolicitud de cancelación en curso; es transitorio.Espera unos segundos y consulta de nuevo.
cancelacion_pendienteEl SAT exige aprobación del receptor antes de cancelar.Consulta GET /:id/estatus-cancelacion para ver el estatus real.
canceladaCancelación confirmada por el SAT.Actualiza tu sistema: el documento ya no es válido fiscalmente.

Entender el rechazo del SAT

Cuando el rechazo viene del SAT o del PAC, el código (por ejemplo CFDI40145 o CP108) explica qué regla no se cumplió. Búscalo en la matriz de errores del CFDI, con el significado y cómo corregirlo, y revisa tu XML antes de enviarlo con el validador de XML gratis.

Preguntas frecuentes

¿Cómo evito timbrar dos veces si falla mi conexión?

Manda el header Idempotency-Key con un texto único. Si repites la petición con la misma clave, la API regresa el comprobante original en vez de timbrar otra vez.

¿Cuándo debo reintentar?

Solo en 409, 429 y 502. Los errores 400, 401, 402, 403 y 404 se corrigen antes de reintentar.

¿Dónde veo la razón real de un rechazo del PAC?

En los campos codigo y detalle de la respuesta 502, o en errorCodigo y errorMensaje al consultar el comprobante.

¿Listo para integrar?

Crea tu cuenta gratis, genera tu API key de sandbox y prueba el timbrado de punta a punta sin consumir timbres.

Crear cuenta gratis Ver precios de la API

Documentación de la API de TimbraMX, versión v1. Actualizada el 27 de octubre de 2026. Todos los ejemplos usan claves de ejemplo: nunca publiques tu API key real.