Errores

Referencia completa de errores de la API de Sifende — formato Problem Details, tipos de error y códigos de rechazo de SIFEN.

Formato de respuesta de error

La API de Sifende usa RFC 9457 Problem Details para todos los errores (excepto errores de autenticación):

{
  "type": "https://sifende.com.py/probs/validation-error",
  "title": "Error de validación",
  "status": 400,
  "detail": "La solicitud contiene 2 error(es) de validación",
  "errores": {
    "receptor.numeroDocumento": "Número de documento es obligatorio",
    "items[0].precioUnitario": "El precio no puede ser negativo"
  }
}

Los endpoints de sesión (/api/v1/contribuyentes/...) usan un envelope ApiResponse diferente. Ver API de Sesión.

Error de autenticación (formato especial)

El filtro de API key retorna un JSON simple, no Problem Details:

{"error": "Invalid or expired API key"}

Tipos de error de Sifende

Tipo (`slug`)	Status	Descripción
`validation-error`	400	Campos inválidos en el body — ver campo `errores`
`invalid-enum-value`	400	Valor de enumeración no reconocido — ver `valoresAceptados`
`invalid-format`	400	Formato de campo incorrecto (fecha, RUC, etc.)
`contribuyente-not-found`	404	Contribuyente no encontrado por ID
`documento-electronico-not-found`	404	DE no encontrado por ID o CDC
`timbrado-not-found`	404	Timbrado no encontrado
`api-key-not-found`	404	API key inexistente o revocado
`certificate-not-found`	404	No hay certificado digital subido
`ruc-not-found`	404	RUC no encontrado en el registro de SIFEN
`evento-not-found`	404	Evento SIFEN no encontrado
`access-denied`	403	Usuario sin acceso al contribuyente
`duplicate-ruc`	409	RUC ya registrado para este usuario
`duplicate-timbrado`	409	Número de timbrado ya existe
`evento-cancelacion-error`	400/409	Error al enviar evento de cancelación
`evento-inutilizacion-error`	400/409	Error al enviar evento de inutilización
`documento-electronico-generation-error`	422	Error al generar el DE (problema de compliance SIFEN)
`kude-generation-error`	422	Error al generar el KuDE PDF
`kude-not-supported`	501	KuDE no disponible para este tipo de documento

Error de validación con detalle por campo

{
  "type": "https://sifende.com.py/probs/validation-error",
  "title": "Error de validación",
  "status": 400,
  "detail": "La solicitud contiene 1 error(es) de validación",
  "errores": {
    "items[0].tasaIVA": "La tasa de IVA debe ser 5, 10 o null para exentos"
  }
}

Error de enumeración con valores aceptados

{
  "type": "https://sifende.com.py/probs/invalid-enum-value",
  "title": "Valor de enumeración inválido",
  "status": 400,
  "detail": "El campo 'tipoDocumento' recibió 'INVOICE', que no es un valor permitido.",
  "campo": "tipoDocumento",
  "valorRecibido": "INVOICE",
  "valoresAceptados": [
    {"codigo": "FACTURA_ELECTRONICA", "descripcion": "Factura electrónica"},
    {"codigo": "NOTA_DE_CREDITO_ELECTRONICA", "descripcion": "Nota de crédito electrónica"},
    {"codigo": "NOTA_DE_DEBITO_ELECTRONICA", "descripcion": "Nota de débito electrónica"}
  ]
}

Códigos de respuesta SIFEN

Cuando SIFEN procesa un lote, retorna un código que Sifende interpreta:

Código SIFEN	Significado	Estado resultante
`0360`	Lote procesado correctamente	DE → APROBADO
`0361`	Lote no existe en SIFEN	Reintento automático
`0362`	Lote aún en procesamiento	Sifende reintenta más tarde
`0363`	Lote con errores de validación	DE → RECHAZADO
`0364`	Lote rechazado por SIFEN	DE → RECHAZADO
`0320`	Evento procesado correctamente	Evento → PROCESADO
`0340`	Evento rechazado	Evento → RECHAZADO

Códigos de rechazo de documentos individuales

Para ver el significado de los códigos de rechazo específicos (ej: 1108, 1302-1306) y cómo corregirlos, consultá Rechazos SIFEN.