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ódigo | Significado | ¿Reintentar? | Qué hacer |
|---|---|---|---|
| 400 | Datos inválidos | No | Lee error, que dice exactamente qué campo falló, y corrige el body. |
| 401 | API key inválida o expirada | No | Revisa el header X-Api-Key; si era de sandbox y expiró, regenérala. |
| 402 | Sin timbres disponibles | No | Compra o recarga timbres desde el portal. |
| 403 | Sin acceso a la API | No | Contrata el módulo de API, o certifica tu cuenta si usabas la key de producción. |
| 404 | Recurso inexistente | No | Revisa el id y que corresponda al mismo ambiente que tu key. |
| 409 | Operación concurrente sobre el mismo documento | Sí, tras unos segundos | Espera y consulta GET /:id para ver en qué quedó. |
| 429 | Límite de peticiones excedido | Sí, con espera | Usa RateLimit-Reset para calcular cuánto esperar. |
| 502 | El PAC rechazó el CFDI o la cancelación | Sí, con la misma Idempotency-Key | Lee 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:
- No expira. Mientras el documento exista, la clave sigue siendo válida.
- No compara el body. Si reusas una clave con un body distinto, se ignora el nuevo y se regresa el documento original. No reutilices una clave para dos operaciones diferentes.
- Si el primer intento falló antes de crear el registro (por ejemplo, un 400 por datos inválidos), no queda nada guardado: puedes corregir el body y reenviar la misma clave.
- Si disparas reintentos en paralelo y no solo secuenciales, deja una pequeña espera antes del segundo intento.
Estados de un comprobante
| Estado | Significado | Qué hacer |
|---|---|---|
timbrando | Petición en curso hacia el PAC; es transitorio. | Si lo ves en un GET, espera unos segundos y consulta de nuevo. |
timbrada | CFDI válido, con uuidFiscal y xml. | Guarda id y uuidFiscal; ya puedes descargar /xml y /pdf. |
error | El PAC rechazó el timbrado. | Revisa errorCodigo y errorMensaje en GET /:id, corrige el dato y manda un POST nuevo. |
cancelando | Solicitud de cancelación en curso; es transitorio. | Espera unos segundos y consulta de nuevo. |
cancelacion_pendiente | El SAT exige aprobación del receptor antes de cancelar. | Consulta GET /:id/estatus-cancelacion para ver el estatus real. |
cancelada | Cancelació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 APIDocumentació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.