Emisso Connect

Todos los códigos que la API puede emitir, con su status HTTP, su semántica de reintento y qué hacer con cada uno.

Cada error llega con la misma forma, pensada para que un humano o un agente sepan qué hacer sin adivinar. Ejemplo real (falta el connectionId en una tool que lo exige):

{
  "error": {
    "code": "validation_error",
    "message": "'sii.rcv.consultar' requiere una conexión concreta.",
    "suggested_fix": "Pasa el connectionId de la conexión de 'sii' (MCP: campo 'connectionId' de execute; REST: header 'X-Connect-Connection'). Lístalos con la tool 'conexiones.estado.consultar'.",
    "request_id": "req_5tYw2nRk88Ma"
  },
  "meta": {
    "request_id": "req_5tYw2nRk88Ma",
    "tool_id": "sii.rcv.consultar",
    "plane": "action",
    "latency_ms": 12,
    "audit_status": "recorded"
  }
}

Reglas de manejo:

Decide por code, nunca por el texto: message puede cambiar, los códigos no.
suggested_fix está escrito para ejecutarse: si tu agente recibe el error crudo, ya sabe el paso siguiente.
request_id correlaciona con la fila de la bitácora y es lo primero que pedirá soporte. Guárdalo en tus logs.
Reintenta solo lo reintentable (columna de cada tabla). El SDK reintenta GET por su cuenta; los execute (POST) nunca se reintentan solos: reintentar a ciegas una acción regulada es la receta del doble pago.

Honorarios

Código	HTTP	Reintentable	Qué significa	Qué hacer
`honorarios_request_not_found`	404	no	La solicitud de honorarios no está disponible para este actor.	Verifica el identificador y usa la identidad que creó la solicitud.
`honorarios_beta_disabled`	403	no	La modalidad de honorarios no está habilitada para esta organización.	Solicita la habilitación de la beta antes de crear una solicitud.
`honorarios_policy_denied`	403	no	Los datos exceden los límites habilitados para honorarios.	Revisa el emisor, receptor, fecha y monto contra la política de tu organización.
`honorarios_duplicate_reference`	409	no	La referencia ya pertenece a otra solicitud del mismo emisor.	Consulta la solicitud original; no cambies la referencia para repetir una emisión incierta.
`honorarios_annulment_conflict`	409	no	La boleta tiene una solicitud de anulación que impide esta operación.	Consulta la solicitud existente. No vuelvas a enviarla ni cambies la clave de idempotencia para repetir la anulación.

Carpeta tributaria puntual

Código	HTTP	Reintentable	Qué significa	Qué hacer
`collection_not_found`	404	no	La solicitud o el documento no están disponibles.	Verifica el identificador y la retención con la organización solicitante.
`collection_not_enabled`	403	no	La obtención puntual no está habilitada.	Solicita la habilitación del piloto.
`collection_configuration_missing`	428	no	Falta configurar el destinatario o la entrega.	Completa la configuración de la organización antes de crear el enlace.
`collection_scope_forbidden`	403	no	La solicitud no autoriza esta operación.	Usa únicamente las operaciones de esta solicitud.
`collection_expired`	410	no	La autorización temporal venció.	Crea una nueva solicitud con autorización del cliente.
`collection_inconclusive`	409	no	No se pudo confirmar el resultado de la emisión.	Revisa el historial; no repitas la emisión automáticamente.
`collection_identity_mismatch`	409	no	El contribuyente no coincide con la solicitud.	Verifica el RUT esperado y el acceso autorizado.
`collection_document_invalid`	422	no	El documento no superó la validación.	Revisa el original sin generar otra carpeta.
`collection_document_too_large`	413	no	El documento supera el límite permitido.	Solicita revisión de la carpeta emitida.
`collection_cleanup_pending`	503	no	El cierre del acceso está pendiente.	Espera la finalización de la limpieza; no vuelvas a emitir.

Petición

Código	HTTP	Reintentable	Qué significa	Qué hacer
`validation_error`	400	no	El input no cumple el esquema de la tool.	Revisa error.details: viene el detalle campo a campo. Corrige el input y reenvía.
`malformed_request`	400	no	El cuerpo no es JSON válido.	Verifica la serialización y el Content-Type antes de reenviar.
`unsupported_media_type`	415	no	El Content-Type no es application/json.	Envía el cuerpo con el header Content-Type: application/json.
`payload_too_large`	413	no	El cuerpo supera el límite de 256 KB.	Reduce el payload; si es una lista, pagina con cursor.
`idempotency_key_missing`	400	no	La operación exige una Idempotency-Key explícita generada por quien llama.	Genera un UUID v4, envíalo como Idempotency-Key y reutilízalo solo para reintentos de esta misma operación.
`idempotency_conflict`	409	no	Esa Idempotency-Key ya se usó con un cuerpo distinto.	Genera una clave nueva para una operación nueva; reutiliza la clave solo para reintentar la misma.
`idempotency_in_progress`	409	sí	Otro intento con esa misma Idempotency-Key todavía está corriendo.	Espera unos segundos y reintenta con la MISMA clave. Generar una nueva para la misma operación es lo que duplica el efecto.
`tool_not_found`	404	no	Ese id de tool no existe para tu organización.	Confirma el id con conexiones.sistemas.listar o search_docs. También cubre conectores que tu organización no tiene habilitados.

Autenticación y permisos

Código	HTTP	Reintentable	Qué significa	Qué hacer
`unauthorized`	401	no	Falta el bearer o el token no es válido.	Envía Authorization: Bearer connect_sk_… con una API key vigente. Si usas OAuth, renueva el access token.
`forbidden`	403	no	La identidad autenticó pero no tiene permiso para esta operación.	Confirma el rol y la organización de la credencial que estás usando.
`scope_not_granted`	403	no	La API key no tiene el scope que la tool exige.	Crea o edita la key en /api-keys con el scope requerido. Recuerda: scopes vacíos significan cero autoridad, no comodín.

Conexiones y sincronización

Código	HTTP	Reintentable	Qué significa	Qué hacer
`connection_ambiguous`	409	no	Hay más de una conexión de ese sistema y la llamada no dijo cuál.	Indica la conexión: header X-Connect-Connection en REST, campo connectionId en MCP y el SDK.
`connection_busy`	409	sí	La conexión está en uso o el servicio alcanzó temporalmente su capacidad.	Espera unos segundos y reintenta. Es una espera transitoria: no necesitas volver a conectar ni ingresar la credencial otra vez.
`connection_disabled`	403	no	La conexión existe pero está deshabilitada.	Reactívala en /connections o usa otra conexión del mismo sistema.
`connection_scope_not_enabled`	403	no	El actor sí tiene el scope que la tool exige, pero la conexión elegida no lo tiene habilitado.	Pide a un owner/admin que habilite el scope en /connections para esa conexión, o usa otra que ya lo tenga activo. Cambiar la credencial del actor no resuelve este error.
`connection_credential_required`	428	no	La conexión no tiene una credencial viva: nunca se vinculó, venció o fue revocada.	Crea un enlace con conexiones.enlace.crear (modo reconectar si la conexión ya existe) y pide a la persona que entregue la credencial de nuevo. No reintentes con la credencial anterior.
`connection_identity_mismatch`	409	no	La respuesta del sistema externo no corresponde a la identidad de esta conexión, o no trajo la prueba de identidad que Connect exige.	No reintentes: la respuesta es determinista. Si el RUT de empresa de la conexión es el correcto, vincula una credencial habilitada en esa empresa. Si el RUT quedó mal al crearla, borra la conexión y créala de nuevo: el RUT de empresa no se puede cambiar.
`connected_account_required`	428	no	La tool exige una cuenta conectada del usuario y no existe.	Completa el flujo de autorización que indica el challenge de la respuesta.
`connection_session_pending`	409	sí	El sistema exige un desafío de navegador y todavía no hay una sesión de portal acuñada.	Ejecuta la sincronización de esa conexión (ella acuña la sesión) o espera la programada, y reintenta.
`connection_sync_in_progress`	409	sí	Ya corre una sincronización de esa conexión para ese período.	Espera a que termine y reintenta, o consulta directamente: puede que ya haya datos.
`connector_onboarding_required`	428	no	El sistema externo exige completar su configuración antes de operar. En Notta, por ejemplo, el certificado digital y los folios.	Lee el mensaje: dice qué falta. Se completa en el portal de ese sistema, no en Connect, y después la llamada funciona sin cambios.
`too_many_pending`	429	sí	La cola de sincronizaciones pendientes de la conexión está llena.	Deja terminar los trabajos en curso antes de encolar más.
`sync_job_not_found`	404	no	Ese id de trabajo de sincronización no existe en tu organización.	Usa los job_ids que devolvió el POST que encoló el trabajo.
`alcance_not_enabled`	403	no	La conexión no tiene habilitado el módulo de datos que la tool pide.	Habilita el alcance en /connections o quítalo del input de la sincronización.
`alcance_scheme_unsupported`	422	no	El módulo de datos pedido no está disponible con el tipo de acceso de esta conexión.	Crea una conexión con el otro acceso, o quita ese módulo del input de la sincronización.
`connector_variant_unsupported`	422	no	Ese sistema sirve este dato en variantes, y la de tu conexión todavía no la lee Connect. El mensaje dice cuál es.	No hay nada que arreglar de tu lado ni en el portal de ese sistema: la credencial y los permisos están bien. Escríbenos para que te avisemos cuando la cubramos.

Límites y plan

Código	HTTP	Reintentable	Qué significa	Qué hacer
`rate_limited`	429	sí	Superaste un límite de tasa.	Espera y reintenta con backoff exponencial.
`quota_exceeded`	429	no	Esta conexión alcanzó su cupo de llamadas del período. Tus demás conexiones siguen funcionando.	Espera el período siguiente o pide una ampliación. Subir de plan no cambia el cupo, y reintentar tampoco.
`feature_not_in_plan`	403	no	Esa función no está incluida en tu plan.	Revisa /billing para habilitarla.
`billing_past_due`	402	no	La organización tiene un pago vencido. Se pausan la sincronización y las conexiones nuevas; la lectura de lo ya persistido sigue funcionando.	Regulariza el pago en /billing. Reintentar no paga la deuda.
`subscription_required`	402	no	La organización no tiene un plan activo. Se pausan la sincronización y las conexiones nuevas; la lectura de lo ya persistido sigue funcionando.	Contrata un plan en /billing. No hay ninguna deuda que regularizar ni tarjeta que falte: no hay suscripción.
`connector_plan_limit`	402	no	Se agotó la cuota del plan que tu organización tiene EN ESE SISTEMA. No es un límite de Connect.	Sube el plan en el portal de ese sistema. El mensaje trae el enlace.

Sistema externo

Código	HTTP	Reintentable	Qué significa	Qué hacer
`upstream_error`	502	sí	El sistema externo (SII, banco) falló o respondió mal.	Reintenta más tarde. Si persiste, el problema está en el sistema externo, no en tu integración.
`upstream_unexpected_response`	502	no	El sistema externo respondió con una forma que Connect no reconoce.	No reintentes: la respuesta es determinista. Repórtalo con el request_id para que actualicemos el conector.
`timeout`	504	sí	La operación superó su tiempo máximo, casi siempre esperando al sistema externo.	Reintenta. Para sincronizaciones largas usa la vía asíncrona y consulta el estado del trabajo.

Webhooks

Código	HTTP	Reintentable	Qué significa	Qué hacer
`webhook_endpoint_not_found`	404	no	Ese endpoint de webhook no existe en tu organización.	Lista tus endpoints con GET /v1/webhooks y usa un id vigente.
`webhook_delivery_not_found`	404	no	Esa entrega de webhook no existe para ese endpoint.	Lista las entregas con GET /v1/webhooks/{id}/deliveries y usa un id vigente.
`invalid_webhook_url`	422	no	La URL del webhook no es válida para recibir entregas.	Usa una URL https pública. Direcciones internas o no resolubles se rechazan.

Internos de Connect

Código	HTTP	Reintentable	Qué significa	Qué hacer
`service_unavailable`	503	sí	Connect no pudo atender la petición por una falla transitoria propia.	Reintenta con backoff. No es un problema de tu petición ni de tu key.
`output_contract_error`	500	no	El resultado interno no cumplió el contrato de salida de la tool.	Es un defecto de Connect. Repórtalo con el request_id.
`handler_error`	500	no	La tool falló de forma no clasificada.	Repórtalo con el request_id si persiste. No reintentes a ciegas.
`internal_error`	500	no	Error interno no clasificado de Connect.	Repórtalo con el request_id. No reintentes a ciegas.
`not_implemented`	501	no	La operación existe en el contrato pero aún no está implementada.	Consulta el changelog o espera su disponibilidad.

Facturador Gratuito SII

Código	HTTP	Reintentable	Qué significa	Qué hacer
`sii_facturador_not_enabled`	428	no	La conexión no tiene habilitado el Facturador Gratuito del SII.	Pide a un owner o admin que habilite el facturador para esta conexión antes de volver a intentarlo.
`sii_dte_variant_not_enabled`	422	no	La variante o versión de contrato DTE no está habilitada en las capabilities de esta conexión.	Elige una variante y versión actualmente habilitadas, o pide a un owner o admin que revise las capabilities.
`sii_dte_validation_failed`	422	no	El candidato o sus totales no cumplen el contrato del DTE antes de cualquier red destructiva.	Corrige los campos indicados en details y genera una previsualización nueva.
`sii_facturador_contract_changed`	502	no	El formulario o la transición del SII ya no coincide con el contrato reconocido por Connect.	No reintentes ni habilites emisión. Repórtalo con el request_id para revisar el conector y su kill switch.
`sii_facturador_not_enrolled`	422	no	La empresa no aparece en el Facturador Gratuito del SII con esta clave: factura con otro sistema, todavía no activó este, o esta persona no la representa ahí.	Desde esta conexión sólo se leen datos. Si la empresa pasa al Facturador Gratuito, o conectas con una clave que sí la represente ahí, vuelve a intentarlo desde el detalle de la conexión: no hace falta crear otra.
`sii_dte_type_not_authorized`	422	no	El SII no autoriza a la persona de esta conexión a emitir ese tipo de documento en esta empresa.	Emite uno de los tipos de 'tiposDte.autorizados' en conexiones.estado.consultar. Si la empresa le da esa autorización en el SII, vuelve a comprobarlo desde el panel «Emisión en el SII» de la conexión.
`sii_preview_token_invalid`	400	no	El token de previsualización no corresponde a esta operación o no supera sus verificaciones.	Genera una previsualización nueva desde la misma organización, conexión y actor. No reutilices este token.
`sii_preview_token_expired`	410	no	El token de previsualización venció y ya no autoriza continuar.	Genera una previsualización nueva y usa su token antes de que expire.
`sii_anulacion_documento_no_encontrado`	404	no	Ese documento no está entre los que se pueden anular por esta vía: la factura no está en los emitidos del Facturador Gratuito del SII, o la boleta no la emitió Connect en esta conexión.	Revisa tipo, folio y fecha. Sólo se anulan facturas emitidas con el Facturador Gratuito y boletas emitidas por Connect en la misma conexión: un documento emitido con otro proveedor no aparece.
`sii_anulacion_en_curso`	409	no	Ya hay una anulación preparada y sin resolver para ese mismo documento.	Termina o deja vencer la anulación en curso antes de preparar otra sobre el mismo documento.
`sii_anulacion_ya_emitida`	409	no	Ese documento ya tiene una nota de crédito de anulación emitida por Connect.	No la anules de nuevo: la nota ya está en el SII. Revísala en el libro de emisión.
`sii_anulacion_no_admitida`	422	no	El Facturador Gratuito del SII no admite esta anulación tal como está el documento.	Lee el motivo en details: un total de boleta que no se puede escribir como neto más IVA redondeado, o un receptor que el SII no habilita o del que no tiene razón social, dirección y giro. Por esta vía no se resuelve; anula el documento en el portal del SII.
`sii_preview_changed`	409	no	La previsualización fresca ya no coincide con la que quedó ligada al token.	Genera y revisa una previsualización nueva. No emitas usando el token anterior.
`sii_emitter_profile_required`	428	no	La conexión todavía no tiene configuradas la actividad y la dirección del emisor.	Pide a un owner o admin que configure el perfil emisor antes de crear otra previsualización.
`sii_emitter_profile_changed`	409	no	La revisión u opción del perfil emisor ya no coincide con el formulario vigente.	Pide a un owner o admin que revise y confirme el perfil emisor; después genera una previsualización nueva.
`sii_preparation_confirmation_required`	428	no	La preparación todavía no está confirmada, y esta llamada no puede confirmarla sola: eso solo ocurre cuando la emisión la pide una clave de API.	Pide a un owner o admin que revise y confirme esta preparación en Connect. Conserva el mismo previewRef y la misma Idempotency-Key para continuar.
`sii_signing_material_required`	428	no	La conexión no tiene material de firma centralizado configurado.	Pide a un owner o admin que configure el certificado antes de intentar una emisión.
`sii_signing_material_invalid`	422	no	El certificado o su credencial de firma fueron rechazados, sin invalidar el acceso de lectura al SII.	Corrige o reemplaza el material de firma. No necesitas volver a vincular el acceso de lectura si sigue vigente.
`sii_emission_rejected`	422	no	La emisión fue rechazada antes de quedar como resultado terminal serializado.	Revisa la clasificación segura, corrige el documento y genera una previsualización nueva. No reintentes la misma emisión a ciegas.
`sii_emission_outcome_unknown`	500	no	La operación cruzó una barrera externa, pero Connect no pudo serializar un resultado concluyente.	No reintentes ni generes otra Idempotency-Key. Repórtalo con el request_id para reconciliar la operación comprometida.
`sii_emission_not_found`	404	no	No hay un documento emitido por Connect con ese operacionId en esta conexión.	Usa el operacionId que devolvió la emisión, con la misma conexión. Si la emisión quedó en resultado desconocido, espera a que se reconcilie.

Catálogo de errores