---
title: "API Response Reference"
description: "Response formats, pagination, errors, and version headers"
canonical: https://y2.dev/docs/api/responses/
---

# API Response Reference

Response formats, pagination, errors, and version headers

Use this page for shared response rules. The [endpoint reference](https://y2.dev/docs/api/reference) defines each operation's fields and exceptions.

## Success representations

The response format depends on the operation. Check its generated reference page.

| Contract kind  | Typical response                                                                           |
| -------------- | ------------------------------------------------------------------------------------------ |
| Collection     | `{ "data": [...], "meta": {...}, "links": {...} }` or operation-specific pagination fields |
| Resource       | `{ "data": {...} }` plus operation-specific fields and headers                             |
| Representation | Plain text, audio metadata, or an optional redirect as documented                          |
| Agent stream   | `text/event-stream` in AI SDK UI or OpenAI-compatible chunk format                         |
| Delete         | `204 No Content` for the documented destructive operations                                 |

Collection cursors are opaque. Store the returned cursor or watermark. Send it back unchanged. Do not construct cursors from record IDs.

## Errors

JSON errors use `application/problem+json`. Read `resolution` for the next action:

```
{
  "type": "https://api.y2.dev/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid API key",
  "instance": "urn:y2:request:req_...",
  "code": "INVALID_API_KEY",
  "requestId": "req_...",
  "resolution": "Send a valid Y2 API key in the Authorization: Bearer header."
}
```

| Status        | Common meaning                                                                       |
| ------------- | ------------------------------------------------------------------------------------ |
| `400`         | Invalid query, ID, cursor, JSON, or request body                                     |
| `401`         | Missing or invalid bearer authentication                                             |
| `402`         | x402 challenge or rejection. Agent Y2 uses this status for plan or credit exhaustion |
| `403`         | Missing scope, ineligible plan, IP restriction, or tenant authorization failure      |
| `404`         | Resource or thread not found in the allowed scope                                    |
| `409`         | Idempotency or resource-state conflict                                               |
| `412`         | `If-Match` does not match the current representation                                 |
| `415` / `422` | Unsupported representation or operation-specific semantic failure                    |
| `429`         | Key, account, endpoint, wallet, or abuse-control limit exceeded                      |
| `500` / `503` | Internal failure, unavailable dependency, or unavailable data path                   |

Keep `X-Request-Id` and the problem `code` in logs. Follow `Retry-After` when the response identifies a temporary limit or availability failure.

## Version and diagnostic headers

| Header                                             | Meaning                                                         |
| -------------------------------------------------- | --------------------------------------------------------------- |
| `X-Y2-API-Version`                                 | `1.0` for v1 operations and `2.0` for v2 operations             |
| `X-Y2-Schema-Version`                              | Shared response-schema version, currently `1.2`                 |
| `X-Request-Id`                                     | Per-request diagnostic identifier                               |
| `ETag`                                             | Strong validator on operations that support conditional writes  |
| `Location`                                         | Canonical URL after resource creation                           |
| `Idempotency-Key`                                  | Echoed retry key on operations that support idempotent creation |
| `X-Y2-Next-Cursor`, `X-Y2-As-Of`, `X-Y2-Watermark` | Collection and change-feed checkpoints where applicable         |

[Endpoint reference](https://y2.dev/docs/api/reference)

[Response migration](https://y2.dev/docs/api/migration-v1-1)
