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.messagepuede cambiar; los códigos no. suggested_fixestá escrito para ejecutarse. Si tu agente recibe el error crudo, ya sabe qué hacer.request_idcorrelaciona 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 suIdempotency-Keydesde 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ódigo | HTTP | Reintentable | Qué significa y qué hacer |
|---|---|---|---|
connection_credential_required | 428 | no | La conexión no tiene credencial viva (clave cambiada o revocada). Enlace con modo: "reconectar". |
connection_sync_in_progress | 409 | sí | 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_granted | 403 | no | La API key no tiene el scope de la tool. Revísala en /api-keys. Scopes vacíos significan cero autoridad, no comodín. |
validation_error | 400 | no | El 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_found | 404 | no | Ese id no existe para tu organización. También cubre conectores no habilitados. |
connection_session_pending | 409 | sí | 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_limited | 429 | sí | Superaste un límite. Respeta el backoff y reintenta. |
upstream_error | 502 | sí | 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
- Catálogo de errores: cada código con qué significa y qué hacer.
- Webhooks: los fallos de sincronización también llegan como evento firmado.
- Límites y planes: los números detrás de 429 y 402.