# Errores y límites de uso

> Index of the TerraLab docs for agents: [llms.txt](https://terra-lab.ai/docs/llms.txt). Every docs page is also served as markdown: add .md to its URL.

Los errores llegan en JSON con un código `error` estable y un `message` escrito para una persona:

```json
{ "error": "auth_required", "message": "This tool needs a TerraLab account. Connect TerraLab in your assistant's settings; see https://terra-lab.ai/mcp." }
```

Ramifica según `error`, nunca según `message`: el texto puede cambiar.

## Errores HTTP

| Estado | `error` | Significado | Qué hacer |
| --- | --- | --- | --- |
| 400 | `invalid_input` | El cuerpo no es un objeto JSON con los argumentos de la herramienta. | Corrige el cuerpo de la solicitud. |
| 400 | `bad_request` | No se pudo leer la solicitud. | Revisa el JSON y las cabeceras. |
| 401 | `auth_required` | No se envió ninguna clave ni token. | Envía `Authorization: Bearer <key>`. |
| 401 | `invalid_token` | La clave o el token no es válido, ha sido revocado o ha caducado. | Crea una clave nueva, o deja que el agente vuelva a iniciar sesión. |
| 401 | `access_revoked` | La aplicación se desconectó desde el panel. | Vuelve a conectar el agente. |
| 402 | `balance_required` | Las llamadas gratuitas del mes se han agotado, o la operación es de pago, y el saldo está vacío. | Añade fondos; la respuesta incluye `hint` y `account_url`. |
| 404 | `not_found` | Esa ruta de la API no existe. | Revisa la URL. |
| 404 | `unknown_tool` | Ninguna herramienta tiene ese nombre. | Lista las herramientas con `GET /v1/tools`. |
| 405 | `method_not_allowed` | Las herramientas se llaman con `POST`. | Usa `POST`. |
| 413 | `too_large` | El cuerpo de la solicitud es demasiado grande. | Envía un archivo más pequeño o menos elementos. |
| 429 | `rate_limited` | Demasiadas solicitudes en el último minuto. | Espera los segundos indicados en `Retry-After` y reintenta. |
| 429 | `daily_limit` | La cuenta alcanzó su tope diario de seguridad. | Reintenta al día siguiente (UTC) o escribe a soporte. |
| 503 | `unavailable` | El servicio de cuentas no respondió. | Reintenta pasados los segundos indicados en `Retry-After`. |

## Errores de herramienta

Una herramienta que se ejecuta pero no puede responder devuelve `200` con `isError: true`. Su `structuredContent` incluye entonces `code`, `message` y, casi siempre, un `hint` que indica qué cambiar: un lugar que no encontró, un área demasiado grande, un país que no cubre.

```json
{
  "structuredContent": { "code": "...", "message": "...", "hint": "..." },
  "content": [{ "type": "text", "text": "..." }],
  "isError": true
}
```

## Qué se cuenta

Una llamada que falla o no encuentra nada no se cuenta: la llamada gratuita o el importe descontado del saldo se devuelve. Solo cuentan las respuestas con resultado.

## Límites de uso

Cada cuenta puede hacer 60 llamadas por minuto. Superado el límite, la API responde `429` con `Retry-After: 60`. Reparte los trabajos por lotes en el tiempo y reintenta con una espera creciente:

```python
import time
import requests

def call(url, headers, body, attempts=5):
    for attempt in range(attempts):
        response = requests.post(url, headers=headers, json=body, timeout=120)
        if response.status_code not in (429, 503):
            return response
        time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))
    return response
```

Reintenta solo `429` y `503`. Un `401` o un `402` no se resolverá con un segundo intento.

Source: https://terra-lab.ai/es/docs/errors · Updated 2026-10-27