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.
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í
Otra operación tiene tomada esta conexión en este momento.
Espera unos segundos y reintenta. El candado es por conexión y se suelta solo.
connection_disabled
403
no
La conexión existe pero está deshabilitada.
Reactívala en /connections o usa otra conexión del mismo sistema.
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. Revisa qué RUT tiene guardado la conexión y vuelve a vincular la credencial si no es el correcto.
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.
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.
payment_method_required
402
no
La prueba terminó y no hay una tarjeta registrada. Se pausan la sincronización y las conexiones nuevas; la lectura de lo ya persistido sigue funcionando.
Agrega un medio de pago en /billing. No hay ninguna deuda que regularizar: falta la tarjeta.
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.