Codigos de Error

Cada error incluye un codigo unico, mensaje descriptivo y sugerencia de solucion.

Formato de error

{
  "success": false,
  "error": {
    "code": "CFDI_003",
    "message": "El certificado CSD ha expirado",
    "details": { "vigenciaFin": "2025-12-15T00:00:00Z" }
  }
}

Autenticacion

AUTH_001401No autorizado

Incluye un API key valido en el header Authorization

AUTH_002401Usuario no encontrado

El API key es valido pero el usuario fue eliminado

AUTH_003403No tienes permisos para esta accion

Tu rol en la empresa no permite esta operacion

Empresa

EMPRESA_001400Datos invalidos

Revisa los campos requeridos: rfc, razonSocial, regimenFiscal, codigoPostal

EMPRESA_002409Ya existe una empresa con este RFC

Usa GET /v1/empresas para encontrar la empresa existente

Certificados CSD

CSD_001400Faltan campos requeridos

Incluye cerBase64, keyBase64 y password

CSD_002400El certificado y la llave no coinciden

Verifica que el .cer y .key sean del mismo par y la contrasena sea correcta

CSD_003400El certificado CSD ya expiro

Renueva tu CSD en el portal del SAT

FIEL (e.firma)

La FIEL se usa para descargar CFDIs del SAT. Es un certificado distinto del CSD.

FIEL_001400Faltan campos requeridos

Incluye cerBase64, keyBase64 y password de la FIEL

FIEL_002400El .cer y .key de la FIEL no coinciden

Verifica que los archivos sean el par correcto y que la contrasena sea correcta

FIEL_003400La FIEL esta expirada

Renueva tu e.firma en el portal del SAT (sat.gob.mx)

FIEL_999500Error interno al procesar la FIEL

Verifica que los archivos sean correctos. Si persiste, contacta soporte.

MISSING_FIEL412La empresa no tiene FIEL configurada

Sube la FIEL via POST /api/empresas/:id/fiel antes de descargar CFDIs

FIEL_EXPIRED412La FIEL esta vencida

Renueva la e.firma y vuelve a subirla

FIEL_DECRYPT500No se pudo desencriptar la FIEL guardada

La clave de cifrado cambio. Vuelve a subir la FIEL.

Descarga de CFDI desde SAT

Errores del flujo asincrono POST /api/cfdi/descargar-por-uuid. Los errores que empiezan con SAT_ vienen directamente del SAT.

DESCARGA_001400Body JSON invalido

Envia un objeto JSON valido con el campo uuid

DESCARGA_002400Datos invalidos

Verifica que el campo uuid este presente y sea string

DESCARGA_003400jobId requerido

Incluye el jobId en la URL: /api/cfdi/descargar-por-uuid/{jobId}

DESCARGA_004404Job no encontrado

El jobId no existe o pertenece a otra empresa

INVALID_UUID400Formato de UUID invalido

Usa el formato XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

CFDI_NOT_FOUND200SAT no encontro el CFDI

Verifica que el UUID sea correcto y que la empresa tenga acceso a ese CFDI (como receptor o emisor)

VERIFICA_TIMEOUT200SAT no termino la solicitud en 5 minutos

Reintenta mas tarde. El SAT puede estar saturado.

EMPTY_PACKAGE200El paquete del SAT vino vacio

Reintenta. Si persiste, el CFDI puede no estar disponible aun en Descarga Masiva.

PARSE_ERROR200El XML se descargo pero no se pudo parsear

CFDI con formato no soportado — reporta a soporte con el UUID

SAT_5002200Se han agotado las solicitudes permitidas

SAT rate-limit. Espera unos minutos antes de reintentar.

SAT_5004200No se encontro informacion

El UUID no existe en el SAT, o no tienes permiso como receptor

SAT_5005200Solicitud duplicada

Ya hay una solicitud identica en proceso — reusa el job anterior

SAT_ESTADO_4200SAT rechazo la solicitud (error)

Revisa el mensaje del SAT en satMensaje

SAT_ESTADO_5200SAT rechazo la solicitud

Solicitud rechazada. Revisa satMensaje.

SAT_ESTADO_6200Solicitud vencida

La solicitud tomo demasiado tiempo. Reintenta.

Facturacion (CFDI)

CFDI_001400Datos invalidos

Revisa que los conceptos tengan claveProdServ, claveUnidad, descripcion, cantidad y precioUnitario

CFDI_002400La empresa no tiene CSD configurados

Sube los certificados via POST /v1/empresas/:id/certificados

CFDI_003400El certificado CSD ha expirado

Renueva tu CSD en el portal del SAT y vuelve a subirlo

CFDI_004404Cliente no encontrado

Crea el cliente primero via POST /v1/clientes

Timbres

QUOTA_001402Se agotaron los timbres disponibles

Adquiere mas timbres. Consulta tu saldo en GET /v1/timbres/saldo

Cancelacion

CANCEL_002404CFDI no encontrado

Verifica el ID del CFDI

CANCEL_003400Status no permite cancelacion

Solo se pueden cancelar CFDIs con status TIMBRADO

CANCEL_004400Motivo 01 requiere folioSustitucion

Incluye el UUID del CFDI que sustituye al cancelado

Nomina

NOMINA_001400Datos invalidos

Revisa salarioDiario, diasPagados y periodicidad

EMPLEADO_002409Ya existe un empleado con ese RFC

Cada RFC debe ser unico por empresa

Codigos HTTP

200OK — Peticion exitosa

201Created — Recurso creado exitosamente

400Bad Request — Datos invalidos o faltantes

401Unauthorized — API key invalido o faltante

402Payment Required — Sin timbres disponibles

403Forbidden — Sin permisos para esta accion

404Not Found — Recurso no encontrado

409Conflict — Recurso duplicado

412Precondition Failed — Falta configuracion previa (ej: FIEL no subida)

500Internal Server Error — Error interno (reportar)