> For the complete documentation index, see [llms.txt](https://docs.guayaba.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guayaba.run/documentation/api-guide/integrations-1.md).

# Errors

All error responses follow a consistent format:

```
{
  "error": "ErrorCategory",
  "message": "Human-readable explanation"
}
```

### Status Codes

| Code  | Error               | Description                                                                           |
| ----- | ------------------- | ------------------------------------------------------------------------------------- |
| `401` | Unauthorized        | Missing, invalid, revoked, or expired API key                                         |
| `402` | Payment Required    | Insufficient credits for the operation                                                |
| `403` | Forbidden           | No active subscription, key lacks required scope, wrong agent, or master key required |
| `404` | Not Found           | Agent or resource does not exist                                                      |
| `409` | Conflict            | Agent is not in the required state (e.g., chatting with a stopped agent)              |
| `422` | Validation Error    | Request body failed validation                                                        |
| `429` | Too Many Requests   | Rate limit exceeded                                                                   |
| `502` | Bad Gateway         | Agent container returned an error or is unreachable                                   |
| `503` | Service Unavailable | Agent container is not running                                                        |

### Error Examples

#### 401 — Invalid API Key

```
{
  "error": "Unauthorized",
  "message": "Invalid or revoked API key"
}
```

#### 402 — Insufficient Credits

```
{
  "error": "Payment Required",
  "message": "Insufficient credits for this operation",
  "required_credits": 10,
  "available_credits": 3
}
```

#### 403 — Missing Scope

```
{
  "error": "Forbidden",
  "message": "This API key lacks the required scope: agent:manage"
}
```

#### 403 — Master Key Required

```
{
  "error": "Forbidden",
  "message": "This endpoint requires a master API key"
}
```

#### 403 — No Active Master Key (Agent Key Creation)

```
{
  "error": "Forbidden",
  "message": "You must have an active master API key before creating agent keys"
}
```

#### 403 — No Active Subscription

```
{
  "error": "Forbidden",
  "message": "An active subscription is required to use the API"
}
```

#### 404 — Agent Not Found

```
{
  "error": "Not Found",
  "message": "Agent not found"
}
```

#### 422 — Validation Error

```
{
  "message": "The given data was invalid.",
  "errors": {
    "message": ["The message field is required."],
    "sessionKey": ["The session key must start with 'api:'."]
  }
}
```

#### 502 — Gateway Error

```
{
  "error": "Bad Gateway",
  "message": "Failed to communicate with the agent container"
}
```

### Troubleshooting

| Symptom                              | Likely cause                                 | Fix                                                  |
| ------------------------------------ | -------------------------------------------- | ---------------------------------------------------- |
| `401` on every request               | Key was revoked or regenerated               | Create a new key from the dashboard                  |
| `403` "active subscription required" | Subscription expired or canceled             | Reactivate your subscription                         |
| `403` "lacks the required scope"     | Agent key missing the needed scope           | Create a new agent key with the correct scopes       |
| `403` "master API key required"      | Using an agent key on a master-only endpoint | Use your master key for CRUD and billing operations  |
| `402` on create/start                | Low credit balance                           | Check balance with `GET /billing/credits` and top up |
| `409` on chat/reload                 | Agent is not running                         | Start the agent first with `POST /agents/{id}/start` |
| `502` on chat                        | Agent container crashed or is unresponsive   | Check agent health with `GET /agents/{id}/health`    |
