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

# Request & Response Format

> Common headers, response structures, and error codes

## Request Format

All requests use JSON and require these headers:

```bash theme={"system"}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

## Successful Responses

Response shapes vary by endpoint, each following its own API spec:

* **Chat Completions** — OpenAI standard response format
* **Claude Messages** — Anthropic standard response format
* **Gemini** — Google standard response format
* **Asynchronous Tasks** — QWave API unified task response format

## Billing Field (usage.cost)

Text and embedding endpoints return the actual charge of each call (quota,
integer) in the `usage` object:

```json theme={"system"}
{
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20,
    "cost": 150
  }
}
```

* **Non-streaming** → `usage.cost` in the response body
* **Streaming (SSE)** → the last data frame carrying `usage` (see [Streaming](/en/docs/streaming))
* **Async tasks** → `pre_consumed_cost` on submission (pre-deduction), `cost` in the terminal
  state (settlement; `0` after refund on failure/cancellation)

For per-call reconciliation, the accumulated value of these fields matches your
account balance deductions exactly.

## Error Responses

Error structures differ slightly across endpoints:

**Synchronous endpoints (chat / messages / images, etc.)** — OpenAI-compatible format with a `type` field:

```json theme={"system"}
{
  "error": {
    "message": "Detailed error description",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}
```

**Asynchronous task endpoints (`/v1/tasks/...`)** — Simplified format with only `message` + `code`:

```json theme={"system"}
{
  "error": {
    "message": "Detailed error description",
    "code": "task_failed"
  }
}
```

## Status Codes

| Code | Meaning                                                                                                                                  | How to Handle                                           |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| 400  | Invalid request parameters                                                                                                               | Check the request payload                               |
| 401  | Authentication failed                                                                                                                    | Verify your API key                                     |
| 402  | Insufficient balance                                                                                                                     | Top up your account                                     |
| 404  | Task or resource not found                                                                                                               | Verify the task\_id and that it belongs to your account |
| 429  | Rate limit exceeded / sliding-window quota exhausted (`code: quota_window_exceeded`, response includes `window`/`used`/`cap`/`reset_at`) | Reduce frequency or retry after `reset_at`              |
| 500  | Internal server error                                                                                                                    | Retry later                                             |