# Errors

> Every error has the same shape, a stable code, and a message you can show people.

When something goes wrong, the API answers with an HTTP status and this shape:

```json
{
  "error": {
    "code": "missing_scope",
    "message": "This key can't do that. It needs the projects:write scope."
  }
}
```

Branch on `code`, which never changes. The `message` is written for people, so you can show it as is, but it may be reworded.

## What to do about each

| Status | Code | What it means | What to do |
| --- | --- | --- | --- |
| 400 | `bad_request` | The request can't be done, like an unknown column or a group from another project. | Read the message; fix the request. |
| 401 | `missing_key` | There's no `Authorization: Bearer` header. | Send the key. |
| 401 | `invalid_key` | The key is wrong, revoked or expired, or its owner left. | Make a new key. |
| 402 | `insufficient_credits` | An AI-powered call needs credits the organization doesn't have. | Ask an admin to add credits. |
| 402 | `budget_reached` | The organization's monthly AI budget is used up. | An admin can raise it under Billing. |
| 402 | `member_limit_reached` | The key's owner reached their own monthly AI credit limit. | Wait for next month, or ask an admin. |
| 403 | `missing_scope` | The key doesn't have the scope this needs. | Use a key with that scope. |
| 403 | `api_disabled` | An admin turned the API off for the organization. | Ask an admin. |
| 403 | `forbidden` | The key's owner isn't allowed to do this, like a viewer making a change. | Use a key from someone who can. |
| 404 | `not_found` | It doesn't exist, or the key's owner can't see it. | Check the id and the owner's access. |
| 409 | `idempotency_key_reused` | That `Idempotency-Key` was used for a different request. | Use a new key for each change. See [idempotency](https://developers.playbookops.ai/idempotency). |
| 409 | `conflict` | The change clashes with the current state. | Read the item again, then retry. |
| 422 | `invalid_request` | A parameter is missing or out of range. | The message names each one. |
| 429 | `rate_limited` | Too many requests from this key this minute. | Wait `Retry-After` seconds. |
| 429 | `daily_limit` | The organization reached its daily limit. | Wait until midnight UTC. |
| 500 | `internal_error` | Something broke on our side. | Retry with backoff; contact support if it continues. |

A `404` doesn't say whether something exists, so a key can't be used to discover things its owner can't see.

## Over MCP

A failed tool call comes back with `isError: true` and the message as its text, so the agent can read it and adjust:

```json
{
  "isError": true,
  "content": [{ "type": "text", "text": "This key can't do that. It needs the projects:write scope." }]
}
```

## Handling errors in code

**Python**

```python
res = api.post(f"/projects/{project_id}/items", json={"title": "Call the venue"})
if res.is_error:
    error = res.json()["error"]
    if error["code"] == "missing_scope":
        raise SystemExit("This key is read-only. Make a Full access key.")
    raise RuntimeError(f"{res.status_code} {error['code']}: {error['message']}")
item = res.json()
```

**JavaScript**

```javascript
const res = await fetch(`${base}/projects/${projectId}/items`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ title: "Call the venue" }),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.message}`);
}
const item = await res.json();
```
