# 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`    |


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.guayaba.run/documentation/api-guide/integrations-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.