KilaSifen Docs

Errores y diagnóstico

Decidí la recuperación por code y details, y guardá el correlation_id.

Toda respuesta de error de la API usa el mismo envelope, incluidos los errores de validación del request, las rutas o métodos inexistentes y los fallos inesperados del servidor. La única excepción es GET /v1/ready: su 503 trae el detalle de readiness en data, con el mismo formato que su 200.

{
  "error": {
    "code": "documents.not_found",
    "message": "Resource was not found.",
    "category": "not_found",
    "correlation_id": "7d33c16a-4ec1-4327-90f2-bc5517c120f2",
    "details": null
  }
}
CampoUso
codeCódigo estable. Decidí con este campo y con details.
categoryGrupo del código, para manejar códigos que todavía no conocés.
messageTexto en inglés, casi siempre genérico (los 422 de reglas dicen «Request validation failed.» y los 409, «Resource conflict.»). No es estable: no lo uses para decidir.
correlation_idEl mismo valor del header X-Correlation-ID, que llega en todas las respuestas, también en las exitosas.
detailsDatos propios de cada código (por ejemplo details.errors o details.max_bytes); null si no hay.
HTTPAcción del consumidor
400El request no se pudo leer (por ejemplo un multipart sin boundary). Corregilo antes de reintentar.
401Revisar o rotar la credencial. No reintentar en loop.
403Pedir el scope que exige la operación (figura en cada operación de la referencia). emitters.owner_not_allowed no es un scope: el alta nombró a otro consumidor como dueño.
404Revisar el ID y que la credencial tenga acceso a ese emisor.
409Colisión de idempotencia (documents.idempotency_key_conflict, documents.external_id_conflict) o precondición no cumplida (certificado activo, CSC, emisor activo, estado del documento, XML todavía no generado). No reintentes sin resolverla.
413Achicar el body o el archivo; el límite va en details.max_bytes.
415Enviar el archivo con el media type esperado.
422El request o la configuración del emisor no permiten procesarlo y no se aplicó ningún cambio. Corregí según code y details.
429Esperar los segundos del header Retry-After (también en details.retry_after_seconds) y aplicar backoff.
500Reintentar con backoff y reportar el correlation_id si persiste.
503Reintentar con backoff porque una dependencia no está disponible.

category toma estos valores: authentication, authorization, validation, invalid_request, not_found, conflict, rate_limit, service_unavailable e internal. invalid_request cubre los errores del framework que no son de validación (400, 405, 406, 415) y los parámetros de consulta inválidos (422 queries.invalid_ruc y queries.invalid_cdc). Un JSON mal formado o un body con otro media type responde 422 request.validation_failed, categoría validation. La lista de categorías puede crecer.

Validación del request

Cuando el body, la query o los parámetros de ruta no cumplen el contrato, la API responde 422 con code: "request.validation_failed" y un problema por entrada en details.errors:

  • loc: dónde está el problema (["body", "factura", "items"]).
  • message: texto en inglés del validador.
  • type: tipo de error del validador (missing, string_pattern_mismatch, json_invalid, value_error...).
  • code: sólo cuando la entrada incumple una regla fiscal con nombre (ver la sección siguiente).

La API nunca devuelve el valor enviado, para no reflejar secretos en los logs del ERP. La excepción es la ruta raw deprecada (sólo platform:admin): los details.errors de documents.raw.generated_xml_invalid_schema son mensajes del validador XSD y pueden citar valores del XML que envió el mismo caller.

{
  "error": {
    "code": "request.validation_failed",
    "message": "Request validation failed.",
    "category": "validation",
    "correlation_id": "7d33c16a-4ec1-4327-90f2-bc5517c120f2",
    "details": {
      "errors": [
        {
          "loc": ["body", "factura"],
          "message": "Value error, documents.cliente.tipo_contribuyente_required",
          "type": "value_error",
          "code": "documents.cliente.tipo_contribuyente_required"
        }
      ]
    }
  }
}

Reglas fiscales

Una regla fiscal incumplida responde 422 y no crea el documento. Llega de una de estas dos formas:

  1. Regla sobre el contenido del payload: dentro de request.validation_failed, con el código de la regla en details.errors[].code y type: "value_error". message es el texto del validador; en las reglas del receptor y de los montos termina con el mismo código, como antes de que existiera code. Las reglas que miran el documento completo (receptor, montos, pagos) se informan en el objeto del documento (loc: ["body", "factura"]), no en el campo: usá code para ubicar el problema. Los códigos se agrupan por prefijo:

    PrefijoQué valida
    documents.cliente.*Receptor: naturaleza, tipo de operación, tipo_contribuyente, RUC y DV, documento de identidad, innominado, dirección y país.
    documents.items.*Ítems: tasa y afectación del IVA, proporcion_gravada, descuentos y anticipos.
    documents.redondeo.*, documents.porcentaje_descuento_global_invalidRedondeo a 50 Gs y descuento global.
    documents.condicion_operacion.*Contado o crédito, formas de pago, cuotas y entrega inicial.
    documents.currency.*Moneda de la operación y tipo de cambio.
    documents.documento_asociado.*Documento asociado de una nota de crédito o de débito.
    documents.codigo_seguridad.*codigo_seguridad enviado: hasta nueve dígitos y distinto de cero.
    documents.informacion_emisor.*informacion_emisor: no vacía y en una sola línea.
    documents.tipo_impuesto.*, documents.responsable_generacion.*Tipo de impuesto y responsable de la generación.
    events.invalid_motivo_*Eventos: motivo de una cancelación, nominación o inutilización, en una sola línea y con al menos 5 caracteres sin contar los espacios de los extremos.

    Los errores de formato del contrato que no son una regla fiscal (un campo faltante, un patrón, el formato de establecimiento, punto o numero) no traen code: identificalos por loc y type.

  2. Regla que depende del emisor o del momento del pedido: con un code propio en el nivel superior del error.

    CódigoCuándodetails
    emitters.fiscal_profile_requiredEl emisor no tiene perfil fiscal: cargalo con PATCH /v1/emitters/{emitter_id} (ver Emisores).emitter_id
    documents.emisor.identity_mismatchemisor o tipo_contribuyente del payload no coinciden con el emisor registrado.field
    documents.fecha_emision.too_oldfecha_emision es anterior a 720 h antes del pedido (el SIFEN rechazaría con 1150).fecha_emision
    documents.fecha_emision.too_far_aheadfecha_emision es posterior a 120 h después del pedido (1151).fecha_emision
    documents.fecha_emision.before_sifen_launchfecha_emision es del 2018-11-22 o anterior; el SIFEN exige una fecha posterior (1156).fecha_emision
    documents.fecha_emision.invalidfecha_emision no se puede leer como fecha y hora.—
    documents.codigo_seguridad.equals_numeroEl codigo_seguridad enviado coincide con el número que la plataforma asignó.—
    documents.documento_asociado.receptor_not_nominatedLa nota ajusta una factura innominada ya nominada y su cliente no es el receptor nominado (ver Eventos). Sin una nominación aprobada responde 409 documents.documento_asociado.nomination_required.nomination_event_id, expected

Los avisos no son errores: el recurso se crea igual (201). Un documento puede traer fiscal_warnings (por ejemplo documents.transmission.emission_far_from_now, ver Facturas) y una inutilización trae warnings (por ejemplo inutilization.extemporaneous, ver Eventos). Registralos en el ERP para revisarlos.

Códigos frecuentes

CódigoHTTPQué hacer
auth.missing_api_key401Enviar el header X-API-Key.
auth.invalid_api_key401La key no existe o fue revocada: rotarla.
auth.insufficient_scope403Pedir el scope de la operación; details no lo nombra, lo indica la referencia.
emitters.not_found404El emisor no existe o la credencial no tiene acceso a él.
documents.not_found404Revisar el document_id y el emisor de la ruta.
documents.idempotency_key_conflict409La misma idempotency_key llegó con otro contenido: details.existing_document_id y details.mismatched_parameters dicen cuál y qué cambió. Usá una clave nueva sólo si es otra intención.
documents.external_id_conflict409Ya existe un documento del emisor con ese external_id, creado con otra idempotency_key o sin ella.
emitters.inactive409El emisor está desactivado: no acepta operaciones nuevas.
certificates.active_required409Activar un certificado del emisor antes de consultar el SIFEN o emitir eventos.
emitters.csc_required409Cargar csc y csc_id del emisor antes de pedir el KuDE.
documents.kude_not_available409El estado del documento no admite KuDE; el estado va en details.internal_status.
documents.xml_not_available409Todavía no hay XML generado: esperar a que el job avance.
documents.cdc_required_for_query409El documento todavía no tiene CDC para consultarlo o reconciliarlo.
request.body_too_large413El body supera el límite; details.max_bytes.
certificates.upload_too_large413El PKCS#12 supera su límite propio; details.max_bytes.
certificates.unsupported_media_type415Enviar el archivo como application/x-pkcs12, application/pkcs12 u application/octet-stream.
queries.invalid_ruc, queries.invalid_cdc422Corregir el RUC o el CDC de la consulta.
sandbox.test_runtime_required422X-Kila-Test-Outcome sólo funciona en un despliegue con KILA_SIFEN_ENVIRONMENT=test (details.required_environment). Ver Sandbox.
limits.rate_exceeded, limits.concurrency_exceeded429Límite de la credencial: esperar Retry-After.
limits.pre_auth_rate_exceeded, limits.pre_auth_concurrency_exceeded429Límite por origen, antes de autenticar: esperar Retry-After.
limits.backend_unavailable503El limitador no está disponible: reintentar con backoff.
emitters.lock_timeout, numbering.lock_timeout503Otra operación del mismo emisor retuvo el bloqueo más de 5 segundos y la operación no se aplicó: reintentala con backoff y, si crea un documento, con la misma idempotency_key.

Los límites de pedidos (limits.*) sólo se aplican en staging y production. Los códigos propios de cancelación, inutilización y webhooks (events.*, webhooks.*) se explican en Eventos y Webhooks.

Errores de ruta y del framework

CódigoHTTPSignificado
request.bad_request400El request no se pudo leer, por ejemplo un multipart sin boundary.
request.route_not_found404La ruta no existe. Revisar la URL y el prefijo /v1.
request.method_not_allowed405El método no aplica a la ruta; el header Allow lista los válidos.
request.not_acceptable406El media type pedido en Accept no está disponible.
request.body_too_large413El body supera el límite configurado.
request.unsupported_media_type415El media type del body no está soportado.
request.validation_failed422El request no cumple el contrato; ver details.errors.
server.internal_error500Fallo inesperado. El detalle interno nunca se expone.

Otro status del framework llega como http.<status>. Un proxy intermedio puede devolver 502 o 504 sin JSON: tratalos como un 5xx reintentable.

Qué declara el contrato

Cada operación de la referencia indica el scope que exige y declara el ErrorEnvelope en sus errores: las rutas autenticadas declaran 401, 403, 404, 422, 429 y 503, y las de los grupos que modifican recursos, además 409 y 413 (también sus lecturas, que pueden responder 409 si el recurso no está listo). GET /v1/auth/check declara 401, 429 y 503, y la carga de certificados, 415. Los 400, 405 y 500 del framework no se declaran por operación: pueden llegar en cualquier ruta.

SDK TypeScript

El SDK TypeScript convierte un envelope de error en KilaSifenError, con status, code, category, correlationId, details y retryable. Un timeout (sdk.timeout), un error de red (sdk.connection_error), un body exitoso ilegible (sdk.invalid_response) o un error HTTP sin envelope (sdk.http_error, por ejemplo el 502 HTML de un proxy, con su status) llega como KilaSifenConnectionError. Las dos clases exponen retryable: es true para 408, 425, 429 y 5xx, y para los timeouts y errores de red.

Diagnóstico

Conservá correlation_id en los logs del ERP y en los tickets de soporte. Nunca agregues la API key, la contraseña del PFX, el CSC, el XML firmado completo ni datos de tarjeta.

En esta página