AVERASE

Errors & pagination

The public API keeps a small, deliberate error surface: four status codes cover every outcome, error bodies are a single JSON object, and list endpoints share one pagination envelope. This page is the complete contract — if you handle everything here, you handle everything the API returns.

Status codes

StatusWhenWhat to do
200Success.Process the response.
401Missing or invalid API key.Alert — the integration is down, not just missing data. Ask the account admin to check or re-issue the key and reconnect.
404Unknown record, or a record outside the key's account.Treat the record as not visible to this key (see below).
422Malformed request parameter (today: a bad since).Fix the request — the body names the parameter and the expected format.

Every error response that carries a body is a single JSON object of the form:

{ "error": "..." }

The one exception is 401, which returns an empty body — authentication failures are answered before any account context exists, so there is nothing safe to say about why.

401 — authentication failed

A 401 means the Authorization: Bearer <token> header was missing, or the token is no longer valid — most commonly because an account admin revoked it from the API tokens page. Revocation takes effect immediately.

For a sync job, a 401 is categorically different from an empty result set: it means every subsequent request will fail until a human intervenes. Surface it as an integration-health alert and prompt the customer to reconnect with a fresh key, rather than retrying silently.

404 — not found, or not yours

The API returns the same 404 for a record that does not exist and for a record that belongs to a different account than the key's. This is indistinguishable by design — the API never confirms the existence of another account's data, and it never silently widens scope to "help" a mismatched account_id.

Examples

{ "error": "Asset not found" }

{ "error": "Account not found" }

What a sync job should do:

  • Fetching a record detail (e.g. GET /api/v1/assets/:id for an id you stored earlier): treat the record as no longer visible and move on. Do not fail the run.
  • Passing an account_id filter: a 404 here almost always means a configuration error — the stored account id doesn't match the key's account. Re-fetch GET /api/v1/accounts (which always returns exactly the key's one account), persist the correct id, and retry.

422 — malformed parameter

Currently the only 422 in the public API is a malformed since filter on GET /api/v1/assets. The body is:

{ "error": "invalid `since` — use ISO-8601, e.g. 2026-07-26T00:00:00Z" }

Send timestamps in ISO-8601 with an explicit timezone (UTC recommended) and this never fires.

Pagination

List endpoints take a page query parameter and wrap their rows in a three-field envelope alongside the data:

  • Name
    page
    Type
    integer
    Description

    The page you received (1-based). Defaults to 1 when the parameter is omitted.

  • Name
    pages
    Type
    integer
    Description

    Total number of pages at the current page size.

  • Name
    count
    Type
    integer
    Description

    Total number of matching rows across all pages.

Rows are ordered newest first — assets by updated_at descending — so page 1 always holds the most recently changed records. The same pagination layer drives the in-app grids, which page at 100 rows; the API envelope tells you the real boundaries per response, so read pages rather than hard-coding a page size.

Walking pages

Request page=1, then increment while page < pages. Because ordering is newest-first, records can shift between pages if data changes mid-walk — for incremental syncs, pin the window with a since cursor (set to the start time of your last successful run) so a walk sees a stable slice:

  1. GET /api/v1/assets?account_id=…&since=<cursor>&page=1
  2. Upsert each row by id; continue until page == pages.
  3. On success, persist the new cursor = this run's start time.

Any polling frequency is fine — the API is read-only, and re-fetching a row you already have is harmless.

Request

GET
/api/v1/assets
curl "https://averase.com/api/v1/assets?page=2" \
  -H "Authorization: Bearer {token}"

Response

{
  "assets": [
    {
      "id": "asset_Mlrnd05DOeK6qILJp1gE9bN3",
      "record_id": "CW-20260727-001519",
      "manufacturer": "Dell Inc.",
      "model": "Latitude 5540"
      // ...
    }
  ],
  "page": 2,
  "pages": 3,
  "count": 242
}
  • Authentication — minting and using API keys.
  • Assets — the list endpoint, its filters, and the full field reference.
  • Certificate verification — the one public endpoint, with its own 404 shape ({"valid": false, "error": "not_found"}).

Was this page helpful?