Erros e limites | Basement Gateway

Erros

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

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

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.