Ayuda

Errores y límites de uso

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

{ "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.

{
  "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:

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.

Actualizado el 2026-10-27