# Pages, dates and errors

## Lists and pages

A list returns `items`, `next_cursor` and, on Stats lists, `total`. Pass `next_cursor` back as `cursor` for the next page; it is `null` on the last. A cursor belongs to the query it came from: change a filter or a sort and start again without it. On the Stats API `limit` is 1 to 1000 and defaults to 100. On the Appraisal API it is 1 to 100 and defaults to 20.

The Stats API echoes the parameters it used in `query`, defaults included. A request with an unknown parameter is redirected to the same query without it; follow the redirect.

## Months and dates

Months are `YYYY-MM`, dates `YYYY-MM-DD`, timestamps ISO 8601 in UTC. A series takes `from` and `to`, or `range`: `1y`, `3y`, `5y`, `10y` or `all` for months; `30d`, `90d`, `1y` or `all` for zone nights. Series run oldest first and carry `bounds`, the first and last point that exist.

## Fields

Apart from `next_cursor`, a field that is unknown is left out rather than sent as `null`. Fields are added without a version change, so ignore fields you do not recognise. Removing or renaming a field means a new version, `/v2/`, announced in advance.

## Errors

Errors are JSON with a stable `error` code, a `message` you can show, and `request_id`, also in the `X-Request-Id` header. Quote the request id when asking for help.

```json
{
  "error": "invalid_parameter",
  "message": "kind must be one or more of: cctld, idn-cctld, legacy-gtld, new-gtld, sponsored, infra, unknown, joined with commas.",
  "details": { "parameter": "kind", "value": "geo",
               "accepted": ["cctld", "idn-cctld", "legacy-gtld", "new-gtld", "sponsored", "infra", "unknown"] },
  "request_id": "d85c68ea-0985-4dfc-9f16-76f8616cb5f8"
}
```

| Status | Code | When |
|---|---|---|
| 400 | `invalid_parameter` | A parameter has a value it does not accept; `details.accepted` lists what it does |
| 400 | `invalid_cursor` | The cursor came from a different query |
| 401 | `unauthorized` | The key is missing or not valid. The Stats API also works with no key |
| 402 | `insufficient_credits` | The wallet cannot cover the request |
| 404 | `not_found`, `job_not_found`, `tld_not_found`, `registry_not_found`, `registrar_not_found`, `group_not_found` | No such endpoint or entity |
| 409 | `already_terminal`, `idempotency_key_reused`, `idempotency_request_in_progress` | The job has already finished, or the `Idempotency-Key` was sent with a different body or is still running |
| 429 | `rate_limited` | Too many requests from this address in a minute; wait `Retry-After` seconds |

The full list of codes is in the [API reference](/api).