Timbra

Appearance

On this page

Errores y códigos de respuesta ​

La API Masivo usa códigos HTTP estándar y devuelve un objeto JSON con status, message y, cuando aplica, errorCode.

Estructura de un error ​

json
{
  "status": "error",
  "message": "Descripción del problema",
  "errorCode": "CODIGO_OPCIONAL"
}
CampoDescripción
statusSiempre error en una respuesta fallida.
messageDescripción legible del problema.
errorCodeCódigo estable para casos que tu integración puede manejar por separado.
messageDetailDetalle adicional del PAC en algunos errores de timbrado JSON.

Códigos HTTP ​

HTTPSignificadoQué hacer
200Operación exitosa.Lee data.uuid, data.cfdi o data.acuse.
400La petición no se pudo procesar.Corrige el cuerpo, el RFC, el saldo o los datos del CFDI.
401Falta la API Key o no es válida.Revisa el header Authorization: Bearer <API_KEY>.
404La ruta no existe.Verifica la URL y el método HTTP.
429Límite de peticiones excedido (Rate Limit).Espera a que termine la ventana de 15 minutos (1,000 en Live, 60 en Test).
500Error interno de Timbra o del PAC.Reintenta con backoff. Si persiste, contacta a soporte.

Códigos de error ​

errorCodeHTTPDescripción
TIMBRES_INSUFICIENTES400No hay saldo de timbres ni suscripción activa para emitir en Live.
USUARIO_NO_ENCONTRADO400No se encontró el usuario asociado a la API Key.

Mensajes comunes ​

Autenticación ​

json
{
  "status": "error",
  "message": "Token de autenticación faltante o formato inválido. Use Authorization: Bearer <API_KEY>"
}
json
{
  "status": "error",
  "message": "API Key inválida o inactiva."
}

Saldo ​

json
{
  "status": "error",
  "message": "Timbres insuficientes. Disponibles: 0, Requeridos: 1",
  "errorCode": "TIMBRES_INSUFICIENTES"
}

Sandbox ​

json
{
  "status": "error",
  "message": "En entorno de pruebas solo se permiten RFCs de prueba oficiales del SAT (ej. EKU9003173C9, AAA010101AAA)."
}

Rate Limit (Límite de peticiones) ​

json
{
  "status": "error",
  "message": "Demasiadas peticiones. Ha excedido el límite de 1000 peticiones por ventana de 15 minutos para esta API Key."
}

Timbrado XML sin data ​

json
{
  "status": "error",
  "message": "El cuerpo de la petición debe contener el campo \"data\" con el XML a timbrar."
}

Cancelación sin UUID ​

json
{
  "status": "error",
  "message": "El parámetro \"uuid\" es requerido."
}

Cancelación sin CSD ​

json
{
  "status": "error",
  "message": "No se encontraron los Certificados de Sello Digital (CSD) para realizar la cancelación."
}

Error interno ​

json
{
  "status": "error",
  "message": "Error interno al procesar el timbrado"
}

Cómo manejar los errores ​

  1. 401: no reintentes con la misma llave. Revisa la variable de entorno, el header y el estado de la llave en el panel.
  2. 400 por saldo: recarga timbres o activa un plan. Reintentar sin saldo no cambia el resultado.
  3. 400 por RFC en Sandbox: usa uno de los RFCs de prueba del SAT. Consulta Ambientes.
  4. 400 por datos del CFDI: revisa el message. El PAC suele indicar el campo o la regla que falló.
  5. 500: aplica reintentos con backoff exponencial. Si el error persiste, comparte el UUID, la hora y el cuerpo de la petición con soporte.

No reintentes errores de validación

Los errores 400 y 401 son deterministas: la misma petición producirá el mismo resultado. Corrige la causa antes de volver a intentar.

Checklist antes de reportar un problema ​

  • La URL incluye /api/masivo y la ruta correcta.
  • El header es Authorization: Bearer <API_KEY>.
  • La llave es del entorno correcto (tmb_live_ o tmb_test_).
  • En Sandbox, el RFC del emisor es un RFC de prueba del SAT.
  • En Live, hay saldo de timbres o una suscripción activa.
  • El CFDI cumple con CFDI 4.0 y los datos del receptor son correctos.
  • Para cancelar, el UUID existe y el motivo es válido.

Si después de revisar el checklist el error continúa, contacta a soporte con el UUID, la hora de la petición y el mensaje completo.