Get Started

Pagination & Errors

Conventions shared by every endpoint: paginated responses, the error envelope, and rate limits.

Pagination

List endpoints return a fixed-size page of results plus a pagination object. Two styles are used depending on the endpoint:

  • Cursor pagination — pass the returned nextCursor as the cursor query parameter to fetch the following page. Preferred for large or frequently changing collections.
  • Offset pagination — pass page and limit query parameters. Used by endpoints that expose a total count.
GET /api/v1/catalog-items?limit=50&cursor=eyJpZCI6...

{
  "data": [ /* up to 50 items */ ],
  "pagination": {
    "limit": 50,
    "nextCursor": "eyJpZCI6Im..."
  }
}

A response with no nextCursor (or an empty data array) means you have reached the end of the collection.

Error envelope

Errors use a consistent JSON shape so clients can handle them uniformly. The HTTP status code reflects the error class; the body carries a machine-readable code and a human-readable message.

{
  "error": {
    "code": "validation_error",
    "message": "Field 'currency' must be a 3-letter ISO code.",
    "details": [
      { "field": "currency", "issue": "invalid_format" }
    ]
  }
}
StatusMeaning
400Bad request — malformed or invalid input.
401Unauthorized — missing or invalid credentials.
403Forbidden — authenticated but not permitted.
404Not found — the resource does not exist.
500 / 503Server error or temporary unavailability — safe to retry with backoff.

Rate limits

Requests are rate limited per credential. When you exceed the limit the API responds with 429 Too Many Requests. Back off and retry after the interval indicated by the Retry-After response header.

Retry safely

Retry only idempotent operations (GET, PUT, DELETE) automatically. Use exponential backoff and a capped number of attempts.