# Claves API y la persona para quien se hace una llamada

Cada código de esta familia: qué significa, su causa más frecuente, qué hacer y quién puede hacerlo.

[Todos los códigos de error](https://www.azothos.ai/es/docs/errors)

### `api_key_invalid`

- **Qué significa**: La clave API de Azoth enviada con la llamada no corresponde a ninguna clave activa.
- **Causa más frecuente**: Una clave revocada o caducada, o una clave copiada con algún carácter de menos.
- **Qué hacer**: Esta clave API de Azoth no es válida (revocada, caducada o mal copiada). Cree una nueva en Ajustes › Acceso.
- **Quién puede hacerlo**: Un propietario o administrador del espacio de trabajo · [Abrir la pantalla](https://www.azothos.ai/dashboard/settings?section=access)

### `api_key_missing`

- **Qué significa**: La llamada no lleva ninguna clave API de Azoth.
- **Causa más frecuente**: Falta la cabecera `Authorization` o `X-Azoth-API-Key`, a menudo porque una variable de entorno no está definida.
- **Qué hacer**: No se envió ninguna clave API de Azoth. Pegue una clave de Ajustes › Acceso.
- **Quién puede hacerlo**: El desarrollador del código que hace la llamada

### `api_key_scope_denied`

- **Qué significa**: La clave es válida, pero está limitada —a ámbitos (las partes de la API que puede llamar), a conectores o a entornos— y esta llamada queda fuera de esos límites. En la ingesta, el campo `dimension` de la respuesta indica qué límite la rechazó: `connector` o `environment`.
- **Causa más frecuente**: Una clave creada para un uso, como la ingesta o la lectura, llamó a otra parte de la API — o envió eventos de un conector o de un entorno para los que no se creó.
- **Qué hacer**: Esta clave API está limitada a algunos ámbitos, conectores o entornos, y esta llamada queda fuera de ellos. Cree una clave que la cubra, o una sin esos límites (sin restricciones).
- **Quién puede hacerlo**: Un propietario o administrador del espacio de trabajo · [Abrir la pantalla](https://www.azothos.ai/dashboard/settings?section=access)

### `api_key_name_taken`

- **Qué significa**: Una clave activa del espacio de trabajo ya tiene el nombre pedido: dos claves activas de un mismo espacio nunca comparten nombre.
- **Causa más frecuente**: Una clave creada antes con este nombre y nunca revocada — una clave caducada conserva su nombre mientras no se revoque.
- **Qué hacer**: Una clave activa de este espacio de trabajo ya tiene este nombre. Elija otro nombre, o revoque antes esa clave en Ajustes › Acceso.
- **Quién puede hacerlo**: Un propietario o administrador del espacio de trabajo · [Abrir la pantalla](https://www.azothos.ai/dashboard/settings?section=access)

### `api_key_role_denied`

- **Qué significa**: La clave es válida, pero su rol —lectura, escritura o administración— es inferior al que esta ruta necesita: una clave de lectura no puede llamar a una ruta que escribe, y una exportación de los ajustes del espacio de trabajo necesita una clave de administración.
- **Causa más frecuente**: Una clave creada de solo lectura, usada por código que envía datos o hace cambios — o una clave de otro rol que el previsto para la integración.
- **Qué hacer**: El rol de esta clave API no permite esta llamada: una clave de lectura no puede escribir, y algunas exportaciones necesitan una clave de administración. Cree una clave con el rol necesario en Ajustes › Acceso.
- **Quién puede hacerlo**: Un propietario o administrador del espacio de trabajo · [Abrir la pantalla](https://www.azothos.ai/dashboard/settings?section=access)

### `ip_not_allowed`

- **Qué significa**: La clave es válida, pero la llamada viene de una dirección fuera de la lista de direcciones IP permitidas del espacio de trabajo: el espacio solo acepta sus claves API desde las direcciones que lista.
- **Causa más frecuente**: Un nuevo servidor, una función en la nube o una red cuya dirección de salida aún no está en la lista — o un proxy que cambia la dirección de la que viene la llamada.
- **Qué hacer**: Esta llamada viene de una dirección fuera de la lista de direcciones IP permitidas del espacio de trabajo. Llame desde una dirección de la lista, o pida a un propietario o administrador que añada esta.
- **Quién puede hacerlo**: Un propietario o administrador del espacio de trabajo

### `on_behalf_of_not_allowed`

- **Qué significa**: Esta llamada se bloqueó: su clave de API no puede nombrar a la persona para quien se hace.
- **Causa más frecuente**: Solo una clave de servicio que un owner o un administrador haya autorizado puede enviar X-Azoth-On-Behalf-Of. Una clave personal siempre habla por su propietario.
- **Qué hacer**: Envíe la llamada sin ese encabezado, o pida a un owner o a un administrador una clave de servicio autorizada a nombrar personas (Ajustes › Acceso).
- **Quién puede hacerlo**: Un propietario o administrador del espacio de trabajo · [Abrir la pantalla](https://www.azothos.ai/dashboard/settings?section=access)

### `human_identity_required`

- **Qué significa**: Esta llamada se bloqueó: no nombra a la persona para quien se hace.
- **Causa más frecuente**: Este espacio de trabajo exige que cada llamada se atribuya a una persona, para que cada decisión muestre quién la tomó.
- **Qué hacer**: Use su clave de API personal, o envíe X-Azoth-On-Behalf-Of (el identificador SCIM o el correo de la persona) con una clave de servicio autorizada a nombrar personas.
- **Quién puede hacerlo**: El desarrollador del código que hace la llamada · [Abrir la pantalla](https://www.azothos.ai/dashboard/settings?section=access)

### `identity_unavailable`

- **Qué significa**: Esta llamada se bloqueó: no se pudo comprobar la persona para quien se hace.
- **Causa más frecuente**: Azoth no pudo leer la clave o las reglas de atribución del espacio de trabajo, y no sirve una llamada que no puede atribuir cuando la atribución es obligatoria.
- **Qué hacer**: Vuelva a intentarlo en un momento.
- **Quién puede hacerlo**: Azoth, o el operador de este despliegue

### `invalid_on_behalf_of`

- **Qué significa**: El encabezado `X-Azoth-On-Behalf-Of` no es un identificador de persona que Azoth pueda leer.
- **Causa más frecuente**: El encabezado está vacío, supera los 256 caracteres o contiene caracteres fuera del ASCII visible.
- **Qué hacer**: X-Azoth-On-Behalf-Of debe tener de 1 a 256 caracteres ASCII visibles: envíe el identificador SCIM o el correo electrónico de la persona.
- **Quién puede hacerlo**: El desarrollador del código que hace la llamada

### `key_not_bound_to_agent`

- **Qué significa**: La pasarela MCP solo responde a una clave API vinculada a un agente — aquel cuyo mandato decide lo que puede llamar — y esta clave no está vinculada a ninguno.
- **Causa más frecuente**: Se usó una clave del espacio de trabajo en lugar de la clave creada para un agente en la pestaña Herramientas MCP, o una clave de agente que se desvinculó después.
- **Qué hacer**: Esta clave API no está vinculada a ningún agente. Cree una clave para el agente en la pestaña Herramientas MCP de Mandatos y entréguela al cliente MCP.
- **Quién puede hacerlo**: Un propietario o administrador del espacio de trabajo · [Abrir la pantalla](https://www.azothos.ai/dashboard/mandats?tab=mcp)

### `invalid_key_identity`

- **Qué significa**: Una clave personal habla siempre por su propietario: no puede nombrar además a otras personas.
- **Causa más frecuente**: Una clave personal creada con la opción de nombrar personas activada.
- **Qué hacer**: Para nombrar personas, cree una clave de servicio con esa opción; una clave personal se crea sin ella.
- **Quién puede hacerlo**: Un propietario o administrador del espacio de trabajo · [Abrir la pantalla](https://www.azothos.ai/dashboard/settings?section=access)
