> ## Documentation Index
> Fetch the complete documentation index at: https://docs.statusstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Status codes and JSON error shapes returned by the StatusStack API.

Failed requests return JSON. Authentication failures and missing API-key permissions use an `error` field; most other failures, including denied access to a resource, use `message`.

## Status codes

| Code | Meaning |
| - | - |
| `200` / `201` | Success, or a resource was created |
| `400` | The request could not be read (MCP REST helpers) |
| `401` | Missing or invalid credentials |
| `403` | Authenticated, but the key lacks the required permission or access to the resource was denied |
| `404` | The resource does not exist, or a scoped key must not see it |
| `422` | Validation failed, or a write would exceed quota |
| `429` | Rate limit exceeded |
| `405` | Method not allowed (for example GET/DELETE on `/v1/mcp/messages`) |

## Response shapes

> **401 Unauthenticated**
>
> Returned when credentials are missing or invalid.
>
> ```json theme={null}
> {
>   "error": "Unauthenticated."
> }
> ```

> **403 Forbidden**
>
> Either the key is missing a permission (`error`) or access to the resource was denied (`message`).
>
> ```json theme={null}
> {
>   "error": "This action is unauthorized."
> }
> ```
>
> ```json theme={null}
> {
>   "message": "This action is unauthorized."
> }
> ```

> **404 Not found**
>
> Unified failure envelope. On stack detail routes, another team's stack is indistinguishable from a missing one.
>
> ```json theme={null}
> {
>   "message": "Not found."
> }
> ```

> **422 Validation failed**
>
> `errors` maps field names to messages.
>
> ```json theme={null}
> {
>   "message": "The name field is required.",
>   "errors": {
>     "name": ["The name field is required."]
>   }
> }
> ```

> **422 Quota exceeded**
>
> Same status as validation, different body. Quota refusals do not return 402.
>
> ```json theme={null}
> {
>   "message": "You have reached your stack limit.",
>   "error": "quota_exceeded",
>   "resource": "stacks",
>   "usage": {}
> }
> ```

> **429 Too many requests**
>
> v1 operations include `Retry-After` (seconds). See [Rate limits](https://docs.statusstack.com/api-reference/rate-limits.md).
>
> ```json theme={null}
> {
>   "message": "Too Many Requests"
> }
> ```

## MCP errors

MCP JSON-RPC refusals use `{ "jsonrpc": "2.0", "error": { "code", "message" } }`. `id` is omitted on 401, 403, and 429 refusals made before the message is read.

Common JSON-RPC codes:

* `-32000` — rate limited
* `-32001` — unauthorized
* `-32002` — subscription required (`data.reason` = `subscription_required`, plus `data.upgrade_url`)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.