# 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:

```json
{
  "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 [#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](/docs/conceptos/bitacora)** 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](/docs/referencia/errores). 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 [#el-handler-de-referencia]

```js
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 [#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. Agrégalo con **Editar clave** en [/api-keys](https://connect.emisso.ai/api-keys): la clave no cambia y aplica desde la próxima llamada. 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](/docs/referencia/errores).

## Próximos pasos [#próximos-pasos]

* [Catálogo de errores](/docs/referencia/errores): cada código con qué significa y qué hacer.
* [Webhooks](/docs/operar/webhooks): los fallos de sincronización también llegan como evento firmado.
* [Límites y planes](/docs/operar/limites): los números detrás de 429 y 402.


---

Esta página es parte de la documentación de Emisso. El índice completo, con cada página y su descripción, está en https://connect.emisso.ai/llms.txt. Esta misma página en HTML: https://connect.emisso.ai/docs/operar/errores.
