---
title: API Fundamentals | Clear Street
description: Understand response envelopes, pagination, and API error handling.
---

## Response Format

All API responses follow a consistent envelope:

```
{
  "data": ...,
  "error": null,
  "metadata": {
    "request_id": "523be14bfc539676885a2ef4629e5322",
    "page_number": 1,
    "total_items": 560,
    "total_pages": 6,
    "next_page_token": "AAAAAAAAAGQAAAAAAAAAZA",
    "previous_page_token": null
  }
}
```

- **data** contains the response payload — a single object for detail endpoints, an array for list endpoints.
- **error** is `null` on success. On failure, it contains a structured error object.
- **metadata** always includes `request_id`. Pagination fields appear only on list endpoints.

## Pagination

Endpoints support `page_size` and `page_token` query parameters:

```
GET /v1/accounts/{account_id}/orders?page_size=6&page_token=AAAAAAAAAGQAAAAAAAAAZA
```

The response metadata includes `page_number`, `total_items`, `total_pages`, `next_page_token`, and `previous_page_token` to help you navigate through results.

```
"metadata": {
       "request_id": "523be14bfc539676885a2ef4629e5322",
       "page_number": 1,
       "total_items": 560,
       "total_pages": 6,
       "next_page_token": "AAAAAAAAAGQAAAAAAAAAZA"
   }
```

## Error Codes

When an error occurs, the response includes a structured error in the `error` field as shown with a code along with a descriptive message.

```
{
  "error": {
    "code": 422,
    "message": "Invalid limit price: must be positive"
  },
  "metadata": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

### Common HTTP Status Codes

| Code  | Meaning                                                                                                                                                                                                                                         |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Success                                                                                                                                                                                                                                         |
| `400` | Bad request — the request body or query parameters failed validation. Inspect `error.message` for the specific field and reason; correct and retry.                                                                                             |
| `401` | Unauthorized — the `Authorization` header is missing or contains an invalid or expired API key. Generate a new key in the web app and retry.                                                                                                    |
| `403` | Forbidden — the API key is valid but lacks permission for this account or action. Verify the account ID and the key’s scope; contact support if access should be granted.                                                                       |
| `404` | Not found — the requested account, order, or resource does not exist or is not visible to this API key. Verify the ID in the path.                                                                                                              |
| `422` | Unprocessable — the request was syntactically valid but rejected by a downstream check (e.g., risk, buying power, restricted list). The `error.code` field identifies the specific rejection reason; see the Order Rejection Reasons reference. |
| `500` | Internal server error — an unexpected failure occurred on the server. Retry with exponential backoff. If the problem persists, contact support and include the `request_id` from the response metadata.                                         |

---