API conventions: Request ID, pagination & errors

Shared conventions across the NextCLi API — the per-response Request ID, list pagination, and the unified error structure.

The following conventions apply across NextCLi API endpoints.

Request ID

Every response carries the X-Request-ID header. Include it when filing a support ticket so we can locate that exact request.

Pagination

List endpoints paginate with limit + offset. Time fields are UTC. Defaults and caps vary per endpoint.

Error structure

On failure the body is {"error": "..."}, combined with standard HTTP status codes:

| Status | Meaning | | --- | --- | | 401 | Unauthenticated | | 403 | Forbidden | | 404 | Not found | | 422 | Invalid input or state | | 429 | Rate limited |