# Errors, Pagination, ETags, And Request IDs

## Error Shape

The OpenAPI contract documents RFC 7807 Problem Details for common errors:

```json
{
  "type": "https://omnius.nexus/problems/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "Optional detail",
  "instance": "request-id",
  "aims:control": "Optional ISO/IEC 42001 control reference"
}
```

Some legacy endpoints may still return simpler `{ "error": "..." }` shapes. Prefer the live `/openapi.json` and endpoint behavior when writing strict clients.

## Common Status Codes

| Code | Meaning |
| --- | --- |
| `400` | Invalid request body or query |
| `401` | Missing or invalid bearer token |
| `403` | Authenticated but scope or tool policy is insufficient |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Internal daemon error |
| `501` | Endpoint intentionally not implemented yet |

## Pagination

List endpoints generally use:

```json
{
  "data": [],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 0,
    "has_more": false
  }
}
```

Use:

```text
?limit=50&offset=0
```

Some list endpoints support family-specific filters such as `status`, `category`, `scope`, `risk`, or `type`.

## ETags

Cacheable GET endpoints may return an `ETag` header. Send it back with:

```text
If-None-Match: "<etag>"
```

When unchanged, the daemon can return `304 Not Modified`.

## Request Correlation

Clients can send:

```text
X-Request-ID: client-generated-id
```

The daemon echoes the request ID where middleware applies and writes it into audit/event surfaces where available.

## API Version Header

Responses carry:

```text
X-API-Version: <semver>
```

Use this for compatibility checks in dashboards and remote clients.