Errores de la API

Cómo interpretar los errores Problem Details de la API de Sifende, resolverlos según su type y decidir cuándo corresponde reintentar la solicitud.

Los errores de operación usan Problem Details: type identifica el problema, status indica el código HTTP y detail explica el caso. Usá type para decidir qué hacer; title y detail son mensajes para personas.

Formato de respuesta

{
  "type": "https://sifende.com.py/docs/solucion-problemas/validation-error",
  "title": "Error de validación",
  "status": 400,
  "detail": "La solicitud contiene 2 error(es) de validación",
  "errores": {
    "receptor.tipoContribuyenteReceptor": "Tipo de contribuyente receptor es obligatorio para un contribuyente",
    "receptor.digitoVerificador": "Dígito verificador es obligatorio y debe contener un dígito"
  },
  "traceId": "8f1c2b3a4d5e6f70"
}

Campo	Uso
`type`	URL que identifica el problema
`title`	Resumen del problema
`status`	Código HTTP
`detail`	Explicación de este caso
`instance`	Referencia a la solicitud, cuando aparece
`traceId`	Identificador para soporte, cuando aparece; también puede estar en `X-Trace-Id`

Las extensiones dependen del error. Por ejemplo, la validación puede incluir errores; una enumeración inválida incluye campo, valorRecibido y valoresAceptados. No supongas que todas las respuestas tienen los mismos campos adicionales.

Autenticación y permisos

Una API key inválida o vencida devuelve 401 con un JSON como este:

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

Los errores de autenticación y permisos 401/403 pueden no usar Problem Details. Revisá las credenciales y el ambiente antes de repetir la solicitud. En NRE, el KuDE requiere que el documento esté APROBADO o APROBADO_OBSERVACION.

Tipos de error de Sifende

HTTP	`type` (último segmento)	Significado
400 / 409	`evento-cancelacion-error`	No se pudo cancelar el documento
400 / 409	`evento-inutilizacion-error`	No se pudo inutilizar el rango
400 / 409 / 503	`evento-nominacion-error`	No se pudo completar la nominación
400	`idempotency-not-supported`	El endpoint no admite `Idempotency-Key`
400	`invalid-enum-value`	Valor de enumeración inválido
400	`invalid-format`	Formato de campo inválido
400	`validation-error`	Datos de la solicitud inválidos
403	`document-archived`	Documento archivado
403	`document-quota-exceeded`	Cupo mensual de documentos agotado
403	`emission-suspended`	Emisión suspendida por falta de pago
403	`plan-operation-not-allowed`	El plan no permite esta operación
404	`certificate-not-found`	Certificado o CSC sin configurar
404	`contribuyente-not-found`	Contribuyente no encontrado
404	`documento-electronico-not-found`	Documento electrónico no encontrado
404	`evento-not-found`	Evento no encontrado
404	`webhook-not-found`	Webhook no encontrado
404	`resource-not-found`	Ruta no encontrada
404	`ruc-not-found`	Documento no encontrado en el padrón
405	`method-not-allowed`	Método HTTP no permitido
409	`document-number-in-use`	El número de documento ya está en uso
409	`document-number-voided`	El número de documento fue inutilizado
409	`documento-xml-not-available`	El documento todavía no tiene XML firmado
409	`idempotency-in-progress`	La operación sigue en proceso
409	`idempotency-key-expired`	La respuesta de la clave expiró
409	`idempotency-outcome-unknown`	Resultado de la operación indeterminado
409	`subscription-stale`	La suscripción cambió
415	`unsupported-media-type`	Tipo de contenido no admitido
422	`configuracion-incompleta`	Configuración del contribuyente incompleta
422	`document-number-requires-voiding`	El número de un rechazado requiere inutilización
422	`documento-electronico-generation-error`	El documento no cumple una regla fiscal
422	`idempotency-key-reused`	Clave utilizada para otro tipo de operación
422	`public-procurement-data-invalid`	Datos de contratación pública inválidos
422	`public-recipient-requires-b2g`	El receptor público requiere B2G
422	`sandbox-operation-not-supported`	El ambiente SANDBOX no admite esta operación
422	`timbrado-mismatch`	El timbrado informado no coincide con el cargado
422	`timbrado-no-vigente`	Timbrado aún no vigente
429	`rate-limit-exceeded`	Límite de consultas alcanzado
500	`internal-error`	Error al procesar la solicitud
500	`kude-generation-error`	No se pudo obtener el KuDE
501	`kude-not-supported`	El tipo de documento no admite KuDE
502	`padron-no-disponible`	Padrón no disponible
503	`idempotency-upstream-unknown`	SIFEN no confirmó el resultado
503	`kude-unavailable`	KuDE no disponible

Reintentos

Ante datos inválidos, corregí la causa antes de volver a enviar.
Ante idempotency-in-progress o idempotency-upstream-unknown, esperá Retry-After y repetí la misma solicitud con la misma clave.
Ante idempotency-outcome-unknown o idempotency-key-expired, detené los envíos y verificá el resultado original.
Un 500 en un POST puede tener efectos. Revisá resultadoIndeterminado y accion; no generes otra clave para recuperar la misma operación.
Un rechazo de SIFEN se consulta como estado: "RECHAZADO" y mensajeRechazo. No equivale a un error HTTP de validación.

Seguí la guía de idempotencia y consultá los rechazos de SIFEN.

Documento archivado

document-archived indica que terminó el período de acceso del plan. Su type es https://api.sifende.com.py/problems/document-archived. No reemitas el documento para resolver el acceso.

Obtener el KuDE

Una respuesta 202 indica que el PDF se está preparando: seguí Location y respetá Retry-After. Consultar no acelera la preparación. Un 500 o 503 al descargar no cambia el estado fiscal del documento ni exige emitirlo de nuevo. Ver Descargar KuDE.