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

# Errors

> Error response format and all error codes returned by the Stewrd API.

## Error Format

All errors return a consistent JSON shape:

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or missing API key. Include your key as: Authorization: Bearer sk-stw_...",
    "docs": "https://docs.stewrd.dev/quickstart"
  }
}
```

| Field     | Type   | Description                      |
| :-------- | :----- | :------------------------------- |
| `code`    | string | Machine-readable error code      |
| `message` | string | Human-readable error description |
| `docs`    | string | Link to relevant documentation   |

## Error Codes

| Code                     | HTTP | Description                                        | Fix                                                                                   |
| :----------------------- | :--- | :------------------------------------------------- | :------------------------------------------------------------------------------------ |
| `invalid_api_key`        | 401  | Key is missing, malformed, or revoked              | Check your Authorization header and key                                               |
| `invalid_body`           | 400  | Request body is not valid JSON                     | Ensure Content-Type is `application/json`                                             |
| `missing_message`        | 400  | The `message` field is missing or empty            | Include a non-empty message in the body                                               |
| `invalid_capabilities`   | 400  | Capabilities array contains invalid values         | Use valid capability names: `chat`, `research`, `documents`, `code`, `data`, `files`  |
| `capability_not_enabled` | 403  | Requested capability is not enabled on the project | Enable the capability in your [project settings](https://stewrd.dev/dashboard)        |
| `plan_restricted`        | 403  | Capability requires a paid plan                    | [Upgrade your plan](https://stewrd.dev/pricing) to access this capability             |
| `quota_exceeded`         | 429  | Monthly request quota exceeded                     | Upgrade your plan or wait for the next billing cycle                                  |
| `rate_limited`           | 429  | Too many requests (60/min limit)                   | Back off and retry after a short delay                                                |
| `invalid_tools`          | 400  | Tool definitions are malformed or exceed limits    | Check tool name format, description, and parameter schema. See [Custom Tools](/tools) |
| `invalid_tool_outputs`   | 400  | Tool outputs array is malformed                    | Each output needs `tool_call_id` (string) and `output` (string)                       |
| `context_expired`        | 404  | Execution context expired or not found             | Submit tool outputs within 5 minutes. Start a new request if expired                  |
| `tool_output_too_large`  | 400  | A single tool output exceeds the 100KB limit       | Reduce the output size or summarize the data                                          |
| `compute_error`          | 502  | The compute service returned an error              | Retry the request; if persistent, contact support                                     |
| `compute_unavailable`    | 502  | Failed to reach the compute service                | Retry the request; check [status.openstatus.dev](https://status.openstatus.dev)       |
| `service_unavailable`    | 503  | Compute service is not configured                  | Check [status.openstatus.dev](https://status.openstatus.dev) for outages              |

## Handling Errors

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.stewrd.dev/v1/agent', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${STEWRD_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ message: 'Hello' }),
  })

  if (!response.ok) {
    const { error } = await response.json()
    console.error(`[${error.code}] ${error.message}`)

    if (error.code === 'rate_limited') {
      // Wait and retry
      await new Promise(r => setTimeout(r, 2000))
    }
  }
  ```

  ```bash cURL theme={null}
  curl -s -w "\n%{http_code}" \
    -X POST https://api.stewrd.dev/v1/agent \
    -H "Authorization: Bearer sk-stw_your_key" \
    -H "Content-Type: application/json" \
    -d '{"message": "Hello"}'
  ```
</CodeGroup>

<Tip>
  All error responses include a `docs` field with a direct link to the relevant documentation page. Use it to quickly find the fix.
</Tip>