# Erros e limites de taxa

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

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

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

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

```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
```

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

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