Errores - Siplex

Formato

Todos los errores siguen el mismo formato JSON:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El campo rutEmpresa es requerido",
    "details": null,
    "requestId": "uuid"
  }
}

Códigos HTTP

Status	Significado
400	Error de validación — revisa los campos enviados
401	No autenticado — token inválido, expirado o faltante
404	Recurso no encontrado
409	Conflicto — operación no puede completarse (ej: folios agotados)
500	Error interno — reintentar o contactar soporte
502	Backend inalcanzable — servicio downstream no responde
504	Timeout — la operación tardó más de 30 segundos

Códigos de error comunes

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Campos inválidos o faltantes
`UNAUTHORIZED`	401	Token no proporcionado o inválido
`SESSION_EXPIRED`	401	Sesión expirada
`NOT_FOUND`	404	Tenant, DTE, folio o recurso no encontrado
`NO_FOLIOS_AVAILABLE`	409	No hay folios disponibles para ese tipo de DTE
`FOLIO_CONFLICT`	409	Conflicto de concurrencia al consumir folio
`API_KEY_NOT_FOUND`	404	API key no encontrada o ya revocada
`WEBHOOKS_NOT_CONFIGURED`	404	La cuenta no tiene webhooks configurados
`GATEWAY_TIMEOUT`	504	Backend no respondió a tiempo
`BAD_GATEWAY`	502	Backend inalcanzable

Certificado digital

Cada código tiene un remedio distinto, así que conviene mostrarlos por separado: alguien con un password mal tipeado que lee “certificado no soportado” abandona el trámite.

Código	HTTP	Qué pasó	Qué hacer
`CERT_PASSWORD_INVALIDO`	400	El password no abre el archivo	Revisar el password que dio el proveedor
`CERT_ILEGIBLE`	400	No es un PKCS#12 válido	Subir el `.pfx` original, sin renombrar ni convertir
`CERT_SIN_RUT`	400	No declara el RUT del titular	No sirve para facturación: pedir uno de firma electrónica simple
`CERT_VENCIDO`	400 / 409	Venció (la fecha va en el mensaje)	Renovarlo con el proveedor
`CERT_DATOS_NO_COINCIDEN`	400	Lo declarado no coincide con el archivo	Corregir los campos de `details.desajustes`
`CERT_NOT_FOUND`	409	El certificado principal no existe	Volver a subirlo
`NO_PRIMARY_CERT`	409	El tenant no tiene certificado principal	Subir uno con `esPrincipal=true`

CERT_VENCIDO sale con 400 al subir y con 409 al emitir: en el segundo caso el certificado ya estaba guardado y venció después, así que es un conflicto de estado y no un problema del pedido. Ver Credenciales para el detalle de qué se valida al subir.

Reintentos

Para errores 5xx, es seguro reintentar con backoff exponencial. Los errores 4xx generalmente no se resuelven reintentando — revisa los campos o el estado del recurso.