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

# Errors and limits

## Errors

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

```json
{ "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](/mcp/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.

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