Ajuda

Erros e limites de taxa

Os erros chegam em JSON com um código error estável e uma message escrita para uma pessoa:

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

Trate o error, nunca a message: o texto pode mudar.

Erros HTTP

Status	`error`	Significado	O que fazer
400	`invalid_input`	O corpo não é um objeto JSON com os argumentos da ferramenta.	Corrija o corpo da requisição.
400	`bad_request`	Não foi possível ler a requisição.	Verifique o JSON e os cabeçalhos.
401	`auth_required`	Nenhuma chave nem token foi enviado.	Envie `Authorization: Bearer <key>`.
401	`invalid_token`	A chave ou o token é inválido, foi revogado ou expirou.	Crie uma nova chave, ou deixe o agente entrar de novo.
401	`access_revoked`	O app foi desconectado pelo dashboard.	Reconecte o agente.
402	`balance_required`	As chamadas gratuitas do mês acabaram, ou a operação é paga, e o saldo está zerado.	Adicione fundos; a resposta traz `hint` e `account_url`.
404	`not_found`	Esse caminho da API não existe.	Verifique a URL.
404	`unknown_tool`	Nenhuma ferramenta tem esse nome.	Liste as ferramentas com `GET /v1/tools`.
405	`method_not_allowed`	As ferramentas são chamadas com `POST`.	Use `POST`.
413	`too_large`	O corpo da requisição é grande demais.	Envie um arquivo menor ou menos feições.
429	`rate_limited`	Requisições demais no último minuto.	Espere os segundos de `Retry-After` e tente de novo.
429	`daily_limit`	A conta atingiu seu teto diário de segurança.	Tente de novo no dia seguinte (UTC) ou escreva ao suporte.
503	`unavailable`	O serviço de contas não respondeu.	Tente de novo após os segundos de `Retry-After`.

Erros de ferramenta

Uma ferramenta que roda mas não consegue responder retorna 200 com isError: true. Seu structuredContent traz então code, message e, na maioria das vezes, um hint dizendo o que mudar: um lugar que ela não encontrou, uma área grande demais, um país que ela não cobre.

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

O que é contado

Uma chamada que falha ou não encontra nada não é contada: a chamada gratuita ou o valor descontado do saldo é devolvido. Só contam as respostas com resultado.

Limites de taxa

Cada conta pode fazer 60 chamadas por minuto. Acima disso, a API responde 429 com Retry-After: 60. Distribua os trabalhos em lote ao longo do tempo e tente de novo com um intervalo crescente:

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

Tente de novo apenas 429 e 503. Um 401 ou 402 não passa em uma segunda tentativa.

Atualizado em 2026-10-27