Pagination and errors

Pagination

Paginated endpoints take page and page_size as query parameters, defaulting to page 1 and 50 per page:

curl "$ALRIK_API_BASE/v1/order_drafts?origin_reference=wh-stockholm-01&page=2&page_size=100" \
  -H "x-api-key: $ALRIK_API_KEY"

They return a fixed envelope:

{
  "page": 2,
  "size": 100,
  "has_next_page": true,
  "items": [ ... ]
}

size echoes page_size

size is the page size you requested, not the number of items returned — on the last page items is shorter than size. Use has_next_page to detect the end of the list.

There is no total count. Page until has_next_page is false:

page = 1
while True:
    res = get("/v1/order_drafts", params={
        "origin_reference": "wh-stockholm-01",
        "page": page,
        "page_size": 100,
    })
    handle(res["items"])
    if not res["has_next_page"]:
        break
    page += 1

Some endpoints cap page_size:

Endpoint	Maximum `page_size`	If you exceed it
`GET /v1/company/orders`	1000	`400 {"detail": "Page size too large"}`
`GET /v1/tours/active`	1000	`400 {"detail": "Page size too large"}`
`GET /v1/vehicles`	500	`422` validation error

Date range limits

The maximum span differs per endpoint — it is not 31 days everywhere:

Endpoint	Maximum span	If you exceed it
`GET /v1/orders`	31 days	`400 {"detail": "Date range too long, max 31 days"}`
`GET /v1/tours/billable`	91 days	`400 {"detail": "Date range too long"}`
`GET /v1/stats/engagement`	91 days	`400 {"detail": "Date range too long"}`
`GET /v1/company/orders`	No limit	A two-year range returns `200`. Page through it instead
`GET /v1/order_drafts`	No limit	Takes optional `created_at` and `converted_at` windows rather than a required range
`GET /v1/tours/active`	—	Takes a single optional `scheduled_date`, defaulting to today

A safe default

If you can, page in 31-day windows everywhere — that works against every endpoint.

Error shapes

There are two different error bodies, and which one you get depends on the kind of failure.

Most errors: `detail`

Permission failures, unknown locations, bad ranges and business-rule violations all return a single string:

{ "detail": "Permission 'allow_order_creation' is required but not granted for this integration" }

Validation errors: a custom envelope

When the request body or query parameters fail schema validation, the response is shaped differently:

{
  "status_code": 10422,
  "message": "[{'type': 'missing', 'loc': ('query', 'end_date'), 'msg': 'Field required', 'input': None}]",
  "data": null
}

Reading the validation envelope

The HTTP status is 422. status_code in the body is Alrik's own error code (10422 for validation failures), not the HTTP status. message is a human-readable description of what failed — log it rather than parsing it.

Branch on the HTTP status: handle this envelope on 422 and the detail shape on everything else.

Status codes

Status	Meaning
`200`	Success
`201`	Created — SCIM user creation
`202`	Accepted — SCIM group creation, processed asynchronously
`204`	No content — SCIM user deletion
`400`	A business rule was broken: missing leg, range too wide, page too large
`401`	The API key is not recognised
`403`	Missing key, missing permission, unowned location, or no company
`404`	Vehicle not found, deleted, or at another location
`409`	Vehicle `external_id` already in use at the location
`422`	Schema validation failed — uses the `10422` envelope
`500`	Internal failure

Retrying

4xx — do not retry. The request needs changing; the body says what to fix.
500 — retry with exponential backoff.

Check before retrying a create

POST /v2/order/draft creates a new order on every call, including a repeated origin_order_number. If a create times out, look for the order in GET /v1/order_drafts by its origin_order_number before sending it again. See Send orders from your ERP.

Pagination​

Date range limits​

Error shapes​

Most errors: detail​

Validation errors: a custom envelope​

Status codes​

Retrying​