> For the complete documentation index, see [llms.txt](https://docs.kickbot.com/dashboard/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kickbot.com/dashboard/api/errors-and-limits.md).

# Errors and limits

Error codes, rate limits, and plan limits for the KickBot API and MCP server, and what your code or agent should do when it gets each one.

## Error format

REST errors use the HTTP status code and this body:

```json
{
  "error": {
    "code": "invalid_input",
    "message": "Invalid value for user_cooldown: Must be a number",
    "fields": { "user_cooldown": "Must be a number" },
    "request_id": "req_Ab12Cd34"
  }
}
```

MCP tools return the same `error` object in a result with `isError: true`. Include the `request_id` when you contact support.

| Code               | HTTP | What it means                                                            | What to do                                                     |
| ------------------ | ---- | ------------------------------------------------------------------------ | -------------------------------------------------------------- |
| `unauthenticated`  | 401  | The key or token is missing, wrong, expired, or revoked.                 | Check the key. Apps reconnect with OAuth.                      |
| `forbidden`        | 403  | You do not have the team permission, or the key is read-only.            | Ask the owner for the permission, or use a read and write key. |
| `not_verified`     | 403  | The Kick channel is not connected to KickBot yet.                        | Finish setup in the dashboard.                                 |
| `limit_reached`    | 403  | The plan limit blocks the change (for example enabled commands on free). | Remove something, or upgrade to premium in the dashboard.      |
| `premium_required` | 403  | The field or action is premium only.                                     | Upgrade to premium in the dashboard.                           |
| `invalid_input`    | 400  | A field is missing or has a wrong value. `fields` says which.            | Fix the input.                                                 |
| `not_found`        | 404  | The item does not exist on this channel.                                 | List the items again.                                          |
| `conflict`         | 409  | The change conflicts with the current state.                             | Read the item again and retry.                                 |
| `rate_limited`     | 429  | Too many requests.                                                       | Wait `retry_after_seconds` (also in the `Retry-After` header). |
| `upstream_error`   | 502  | A service KickBot depends on (for example Kick) failed.                  | Try again later.                                               |
| `internal_error`   | 500  | Something went wrong at KickBot.                                         | Try again later. Contact support if it continues.              |

## Rate limits

Limits are per key or connected app. Test alerts, downloads, and voice cloning also have the same limit per channel, shared by all keys and apps on it. Normal use stays far below them.

| Kind of request                | Limit                         |
| ------------------------------ | ----------------------------- |
| All requests                   | 120 per minute, 3000 per hour |
| Test alerts and test AI images | 20 per minute                 |
| Clip and VOD downloads         | 10 per minute, 100 per day    |
| Voice cloning                  | 5 per minute, 30 per day      |

Successful REST responses have `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. A `429` response has a `Retry-After` header with the number of seconds to wait.

## Plan limits

The API follows the same plan limits as the dashboard. `get_account_overview` returns the limits for your channel, for example how many custom commands and timed messages can be on at a time on the free plan, and the daily VOD downloads.

## Questions?

Contact <support@kickbot.com> or the `#support` channel on [Discord](https://discord.gg/MAg3gBbc89).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kickbot.com/dashboard/api/errors-and-limits.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.