Tu integración por API

Manejo de errores

Cada error de Emisso llega con un código estable, una acción sugerida y un correlativo de soporte. Esta guía enseña a manejarlos; el catálogo completo vive en la referencia.

Todo error llega con la misma forma, pensada para que un humano o un agente sepan el paso siguiente sin adivinar:

{
  "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" }
}

Las reglas

  • 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 qué hacer.
  • request_id correlaciona con la bitácora y es lo primero que pedirá soporte. Guárdalo en tus logs.
  • Reintenta solo lo reintentable. Cada código declara su semántica de reintento en el catálogo. Un execute (POST) se reintenta solo cuando tu código lo decide. Una acción que emite o anula lleva su Idempotency-Key desde el primer intento y se reintenta con la misma: reintentada sin clave, o con una nueva, puede ejecutarse dos veces.

El handler de referencia

const res = await fetch("https://connect.emisso.ai/api/v1/tools/sii.rcv.consultar/execute", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EMISSO_CONNECT_API_KEY}`,
    "X-Connect-Connection": connectionId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input }),
});
const { data, error } = await res.json();
if (error) {
  switch (error.code) {
    case "connection_credential_required":
      // La clave cambió o fue revocada: pide reconectar con un enlace nuevo.
      return pedirReconexion(connectionId);
    case "rate_limited":
      // Reintentable: espera y vuelve a intentar.
      return reintentarLuego();
    default:
      log.error({ code: error.code, requestId: error.request_id }, error.suggested_fix);
      throw new Error(error.message);
  }
}

Los errores que vas a ver primero

CódigoHTTPReintentableQué significa y qué hacer
connection_credential_required428noLa conexión no tiene credencial viva (clave cambiada o revocada). Enlace con modo: "reconectar".
connection_sync_in_progress409síPor POST /v1/connections/{conn}/syncs: ya hay un sync de ese período en cola o corriendo. Espera y reintenta. La tool conexion.sincronizar no lo devuelve: responde yaEnCurso: true.
scope_not_granted403noLa API key no tiene el scope de la tool. Agrégalo con Editar clave en /api-keys: la clave no cambia y aplica desde la próxima llamada. Scopes vacíos significan cero autoridad, no comodín.
validation_error400noEl input no cumple el schema; error.details trae el detalle campo a campo. También cubre el connectionId ausente del ejemplo de arriba.
tool_not_found404noEse id no existe para tu organización. También cubre conectores no habilitados.
connection_session_pending409síEl acceso a ese sistema todavía no está listo, y solo la sincronización puede prepararlo. Corre la sincronización de esa conexión o espera la programada.
rate_limited429síSuperaste un límite. Respeta el backoff y reintenta.
upstream_error502síEl SII o el banco fallaron al otro lado. Reintentar suele bastar.

El catálogo completo, con todos los códigos agrupados por dominio y una acción por cada uno, está en la referencia de errores.

Próximos pasos

En esta página