Errors and limits | Basement Gateway

Errors

When a call fails, the HTTP API answers a status and a body with a code and a message:

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

Status	`code`	Meaning	What to do
`400`	`invalid_request`	The arguments are not valid, or the tool refused them. The message says why.	Correct the arguments.
`401`	`unauthorized`	The key is missing, wrong, revoked or expired.	Check the key. Connect again if it was revoked.
`403`	`forbidden`	The key’s access level does not allow the call.	Ask an admin to change the access level.
`404`	`not_found`	There is no tool with this name.	Check the name in Tools.
`429`	`rate_limited`	The key made too many calls in a minute.	Wait and try again.
`500`	`internal_error`	Basement failed to complete the call.	Try again.
`502`	`service_error`	A connected service failed or refused the call. The message is the service’s own.	Read the message. Check the connection in Basement.

The SDKs raise one error type for all of these: BasementGatewayError in TypeScript and ApiError in Python. Both carry the status and the body.

An item that the key cannot use reads as not found. For example, reading a file in a folder that the key cannot reach answers 400 with “File not found”.

Limits

Limit	Value
Calls for one key	240 per minute
A file written through the Gateway	5 MB
A text file read inline by `read_file`	256 KB
Results of `search`	25 items

Above the limit of calls, the Gateway answers 429 until the minute ends. The SDKs try again by themselves, up to 2 more times.

Through MCP

An agent gets the same refusals as a JSON-RPC error, with the same message. A tool that the key’s access level does not allow is not in the agent’s list of tools.