> ## Documentation Index
> Fetch the complete documentation index at: https://docs.utmkit.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores

> Cada rechazo vuelve en un solo sobre, con un código de una lista cerrada y una frase que una persona puede leer.

La API nunca responde un rechazo con un estado desnudo. Cada uno lleva el mismo sobre:

```json theme={null}
{
  "error": {
    "code": "governance_refused",
    "message": "utm_source must be lowercase: Newsletter → newsletter."
  }
}
```

`code` y `message` siempre están ahí. Se agrega uno de `details`, `permission` o
`retry_after_seconds` cuando aplica.

* `code` es una palabra de una lista cerrada, para que tu programa se ramifique sobre ella.
* `message` es una frase, para que la lea una persona. Es la misma frase que muestra la
  consola para el mismo rechazo, así que un comercializador y un integrador que ven el mismo
  problema ven las mismas palabras.
* `details` aparece en `invalid_input`: un mapa de nombre de campo a una lista de mensajes
  cuando la propia validación del espacio de trabajo rechazó, o de puntero JSON
  (`/destination`) a un mensaje cuando la solicitud falló la validación de esquema.
* `permission` aparece en `missing_permission`: el permiso que le falta al token.
* `retry_after_seconds` aparece en `rate_limited`, y en el `limit_reached` por hora.

## Los códigos

La lista vive en el esquema `Error` de la referencia de la API, y ese esquema se genera
desde la API misma, así que siempre está actualizado. En resumen, los códigos caen en
cuatro familias:

* **La puerta** — `unauthenticated` (401), `subscription_required` y
  `subscription_ended` (402), `missing_permission` y `role_forbids` (403),
  `rate_limited` (429). Ver [Autenticación y tokens](/es/developers/authentication) y
  [Límites de solicitudes](/es/developers/rate-limits).
* **El plan** — `plan_forbids` (403) cuando el plan no incluye la función,
  `limit_reached` (429) cuando se alcanza uno de los dos límites de abuso en la página
  [Límites de solicitudes](/es/developers/rate-limits), con `Retry-After` solo para el que
  es por hora. Una ventana de informe que el plan no alcanza es `invalid_input` (422), abajo.
* **Las reglas** — `governance_refused` cuando la convención, los valores aprobados o las
  reglas de dependencia del espacio de trabajo rechazan la entrada, `scanner_refused`
  cuando el destino falló el escaneo de seguridad, `duplicate_link` cuando el espacio de
  trabajo ya tiene un enlace con exactamente ese destino etiquetado (409, el único
  conflicto del conjunto: el mensaje nombra el enlace existente, y lo correcto es usarlo en
  vez de reintentar). Los dos primeros son 422.
* **La solicitud** — `invalid_input` (422) con `details`, y `not_found` (404). Un recurso
  de otro espacio de trabajo y uno que no existe son la misma respuesta, a propósito.

## Cómo reporta el servidor MCP las mismas cosas

Una llamada a herramienta nunca devuelve este sobre. Un rechazo es un **resultado de
herramienta** marcado como error, cuyo texto es el `message` de arriba, así que el asistente
puede transmitirlo o reparar la entrada. Un error a nivel de protocolo significa que el
cliente habló mal; un rechazo significa que el producto dijo que no. Los rechazos de la
puerta (401, 402, 429) sí aplican al servidor MCP, y fallan la conexión con ese estado HTTP
en vez de un resultado de herramienta, porque un token que no se admite no tiene
herramientas que listar.