Pagination and errors

List endpoints return a cursor-paginated envelope, and every error uses the same problem+json shape. This page covers both.

Cursor pagination

A list response wraps the rows in a data array alongside a pagination object:

{
  "data": [],
  "pagination": {
    "nextCursor": "Tjo3ZDJlNGM4NC05YTZmLTFiNWU4ZDBjMmEzNw",
    "previousCursor": null,
    "limit": 10
  }
}

Parameters

Both parameters are optional query-string values:

• limit: how many rows to return per page. Defaults to 100, and must be between 1 and 1000.
• cursor: an opaque token marking a position in the list. Omit it to start from the first page.

Paging through results

Each response returns the cursors for the adjacent pages. To move forward, send the nextCursor value back as the cursor parameter:

curl --fail-with-body "https://integrations.allomancy.net/v1/products?limit=10&cursor=Tjo3ZDJlNGM4NC05YTZmLTFiNWU4ZDBjMmEzNw" \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"

import requests

response = requests.get(
    "https://integrations.allomancy.net/v1/products",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
    params={"limit": 10, "cursor": "Tjo3ZDJlNGM4NC05YTZmLTFiNWU4ZDBjMmEzNw"},
)
print(response.json())

const response = await fetch(
  "https://integrations.allomancy.net/v1/products?limit=10&cursor=Tjo3ZDJlNGM4NC05YTZmLTFiNWU4ZDBjMmEzNw",
  {
    headers: { "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w" },
  },
);
console.log(await response.json());

<?php
$ch = curl_init("https://integrations.allomancy.net/v1/products?limit=10&cursor=Tjo3ZDJlNGM4NC05YTZmLTFiNWU4ZDBjMmEzNw");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

previousCursor pages backward the same way. When nextCursor is null, you have reached the last page. Cursors are opaque: pass them back exactly as received, and do not construct or decode them yourself.

Filtering

Some list endpoints accept optional filter query parameters, documented on each endpoint's own page. The API filters the result set; it does not sort it.

Because the cursor encodes only a position, it does not carry your filters. Re-send the same filter parameters on every page request so each page is drawn from the same filtered set. Changing the filters starts a new result set, so begin again without a cursor.

Pagination errors

A malformed pagination request returns 400 with one of these messages:

Error format

Errors use the RFC 9457 problem+json format, served with the application/problem+json content type:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Limit must be between 1 and 1000.",
  "instance": "/v1/products",
  "errors": ["Limit must be between 1 and 1000."]
}

The fields are:

• status: the HTTP status code.
• title: a short label for the status, such as Bad Request or Not Found.
• detail: a human-readable description. When several validation messages apply, they are joined into one string.
• instance: the path of the request that produced the error.
• errors: an array of the individual validation messages. This field is present only when there are validation messages; a 404 for a missing resource, for example, omits it.

A 404 uses the same shape with the title Not Found:

{
  "status": 404,
  "title": "Not Found",
  "detail": "The requested resource was not found.",
  "instance": "/v1/products/3a1f0c9b-7d2e-4c84-9a6f-1b5e8d0c2a37"
}

Where errors come from

• 400 and 404 come from the request itself: a 400 for invalid input (a bad pagination parameter, a request body that fails validation) and a 404 for a resource or resident that cannot be found. Both carry the problem+json body above.
• 401, 403, and 429 come from the authentication, authorization, and rate-limiting layers before the endpoint runs. For these, rely on the status code and its meaning (see Authentication) rather than a response body.