> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.basement.chat/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.basement.chat/_mcp/server.

# Erros e limites

## Erros

Quando uma chamada falha, a API HTTP responde um status e um corpo com `code` e `message`:

```json
{ "error": { "code": "forbidden", "message": "Role lacks write access" } }
```

As mensagens vêm em inglês.

| Status | `code`            | Significado                                                                        | O que fazer                                           |
| ------ | ----------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `400`  | `invalid_request` | Os argumentos não são válidos, ou a ferramenta recusou. A mensagem diz o motivo.   | Corrija os argumentos.                                |
| `401`  | `unauthorized`    | A chave está ausente, errada, revogada ou vencida.                                 | Confira a chave. Conecte de novo se ela foi revogada. |
| `403`  | `forbidden`       | O nível de acesso da chave não permite a chamada.                                  | Peça a um administrador para mudar o nível de acesso. |
| `404`  | `not_found`       | Não existe ferramenta com esse nome.                                               | Confira o nome em [Ferramentas](/pt-br/mcp/tools).    |
| `429`  | `rate_limited`    | A chave fez chamadas demais em um minuto.                                          | Espere e tente de novo.                               |
| `500`  | `internal_error`  | O Basement não conseguiu concluir a chamada.                                       | Tente de novo.                                        |
| `502`  | `service_error`   | Um serviço conectado falhou ou recusou a chamada. A mensagem é do próprio serviço. | Leia a mensagem. Confira a conexão no Basement.       |

Os SDKs lançam um só tipo de erro para todos esses casos: `BasementGatewayError` no TypeScript e `ApiError` no Python. Os dois trazem o status e o corpo.

> **Note**
>
> Um item que a chave não pode usar aparece como não encontrado. Por exemplo, ler um arquivo em uma pasta que a chave não alcança responde `400` com "File not found".

## Limites

| Limite                                      | Valor          |
| ------------------------------------------- | -------------- |
| Chamadas de uma chave                       | 240 por minuto |
| Arquivo gravado pelo Gateway                | 5 MB           |
| Arquivo de texto lido junto com `read_file` | 256 KB         |
| Resultados de `search`                      | 25 itens       |

Acima do limite de chamadas, o Gateway responde `429` até o minuto terminar. Os SDKs tentam de novo sozinhos, até mais 2 vezes.

## Pelo MCP

Um agente recebe as mesmas recusas como um erro JSON-RPC, com a mesma mensagem. Uma ferramenta que o nível de acesso da chave não permite não aparece na lista de ferramentas do agente.