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

# Responses

> Understanding API response format and error handling

## Response Format

All successful API responses follow this structure:

```json theme={null}
{
  "results": [...],
  "filter": {...},
  "sort": {...},
  "pagination": {
    "page": 1,
    "perPage": 50,
    "pageCount": 10,
    "resultCount": 487
  }
}
```

### Response Fields

* `results` - Array of result objects
* `filter` - Applied filter (if any)
* `sort` - Applied sort configuration
* `pagination` - Pagination metadata
  * `page` - Current page number
  * `perPage` - Results per page
  * `pageCount` - Total number of pages
  * `resultCount` - Total number of results matching the query

## Metric Objects

Numeric metrics on assets and tokens are returned as objects containing the current value plus historical snapshots and deltas:

```json theme={null}
{
  "circulating_market_value_dollar": {
    "val": 2394947347.33,
    "val_7d": 2118658299.28,
    "val_30d": 1950000000.00,
    "val_90d": 1200000000.00,
    "chg_7d_amt": 276289048.05,
    "chg_7d_pct": 13.04,
    "chg_30d_amt": 444947347.33,
    "chg_30d_pct": 22.82,
    "chg_90d_amt": 1194947347.33,
    "chg_90d_pct": 99.58
  }
}
```

| Field         | Description                    |
| ------------- | ------------------------------ |
| `val`         | Current value                  |
| `val_7d`      | Value 7 days ago               |
| `val_30d`     | Value 30 days ago              |
| `val_90d`     | Value 90 days ago              |
| `chg_7d_amt`  | Absolute change over 7 days    |
| `chg_7d_pct`  | Percentage change over 7 days  |
| `chg_30d_amt` | Absolute change over 30 days   |
| `chg_30d_pct` | Percentage change over 30 days |
| `chg_90d_amt` | Absolute change over 90 days   |
| `chg_90d_pct` | Percentage change over 90 days |

Not all fields are present on every metric — only periods with available data are included.

## Timeseries Responses

Aggregate timeseries endpoints (`/v4/assets/aggregates/timeseries`, `/v4/tokens/aggregates/timeseries`) return a different shape. Each result contains a `measure` descriptor, a `group` descriptor, and an array of `points`:

```json theme={null}
{
  "results": [
    {
      "measure": {
        "id": 3,
        "slug": "net_asset_value_dollar",
        "name": "Net Asset Value (Dollar)",
        "unit": "dollar"
      },
      "group": {
        "id": 51,
        "type": "asset",
        "name": "Circle USYC",
        "color": "#2A3758"
      },
      "points": [
        ["2023-10-19", 1.01577],
        ["2023-10-20", 1.01590]
      ]
    }
  ],
  "pagination": { "page": 1, "perPage": 30, "pageCount": 1, "resultCount": 1 }
}
```

* `measure` — the metric being returned (use the [Data Catalog](https://app.rwa.xyz/catalog) to discover available measures)
* `group` — what the data is grouped by (e.g., a specific asset, token, or asset class)
* `points` — array of `[date, value]` pairs in chronological order

## Error Handling

### HTTP Status Codes

| Status | Description                                        |
| ------ | -------------------------------------------------- |
| `200`  | Success                                            |
| `400`  | Bad Request — invalid query, filter, or parameters |
| `401`  | Unauthorized — missing or invalid API key          |
| `405`  | Method Not Allowed — endpoint only supports GET    |
| `429`  | Too Many Requests — rate limit exceeded            |
| `500`  | Internal Server Error                              |

### Error Response Format

```json theme={null}
{
  "message": "Error description"
}
```

### Common Errors

#### Invalid Filter

```json theme={null}
{
  "message": "Invalid filter format"
}
```

#### Invalid Operator

```json theme={null}
{
  "message": "Invalid operator 'invalidOp' for field 'market_value_dollar'"
}
```

#### Rate Limit Exceeded

When you exceed a rate limit, the API returns `429` with headers indicating when you can retry. See [Rate Limits](/api/overview#rate-limits) for details.

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710000000
```