Skip to Content
Pagination & errors

Pagination, errors and caching

Beta.

Responses

Successful reads return JSON with Content-Type: application/json. Individual resources use { "data": { ... } }; collections add pagination and as_of. Nullable fields are present as null. An empty collection returns 200 with data: [].

Dates are ISO 8601 UTC timestamps. Input date filters must include a timezone. All money is in NOK, represented as integer øre. 10000 means 100 kr. IDs are opaque, case-sensitive strings. Treat image URLs as URLs, not stable IDs. Render them directly; never append the API secret.

Pagination

Follow the returned next_cursor; do not parse it. Preserve the original query parameters. There are no offsets, page numbers or total-count guarantees. Cursors expire after one hour and cannot be used with another key or query. Stop when has_more is false and next_cursor is null. An empty page can still have a next cursor.

An as_of timestamp fixes the event-time filter for a traversal. Records are read live, so edits may move events between pages. Deduplicate on IDs and restart periodically to reconcile. updated_at is event metadata’s last edit time; ticket availability/prices can change without that timestamp changing. It is not a complete change-feed cursor.

Errors

{ "error": { "code": "invalid_query", "message": "The status filter contains an unsupported value.", "request_id": "req_example" } }
HTTP statusCodeHandling
400invalid_queryCorrect unsupported/duplicate parameters, malformed values or date bounds.
400invalid_cursorRestart pagination from the first page.
401unauthorizedCheck the key and its validity; replace it if revoked or lost.
403api_access_disabledAsk the organization admin or Stello about organization access.
403insufficient_scopeUse a key granting events:read. For ticket lookup, turn on the key’s Ticket lookup setting.
409ambiguous_ticket_codeTwo tickets of the event were found with the same code, which should not happen. Look the ticket up by its full ID.
404not_foundResource is missing or outside the key’s organization/event access.
405method_not_allowedUse GET; writes are unsupported. Response includes Allow: GET.
429rate_limitedWait for Retry-After seconds before retrying.
500internal_errorRetry with bounded exponential backoff and jitter.
503temporarily_unavailableRetry with backoff, honoring Retry-After when present.

Responses include X-Request-Id. Include that ID when reporting errors; do not include the key. Error messages are human-readable and may change. Branch on code, not message. Infrastructure failures before the API handler may return a non-JSON error; check the HTTP status before parsing.

Rate limits

Initial proposed budgets are 60 requests per minute per key with a burst of 20, and 300 per minute per organization with a burst of 100. Multiple keys share the organization’s budget. These are the beta values and can change; changes are announced in the changelog. A 429 includes Retry-After as a positive integer number of seconds. Do not retry 400, 401, 403 or 404 automatically.

Website caching

Authenticated responses use Cache-Control: private, no-store. They may contain drafts and private ticket types. Do not put raw responses into a shared CDN cache or publicly expose an unrestricted API proxy.

Your server can periodically retrieve events and store a public projection containing only published, non-past events and publicly listed ticket types. Refresh that projection on a short schedule appropriate for your site, and purge it when access is withdrawn or publication changes are detected. A suggested starting refresh interval is 60 seconds. Cached availability may change before checkout; Stello checkout determines the actual available seats and final charge.

Compatibility

The /v1 contract permits additive fields. Ignore unknown response fields and handle unfamiliar enum values gracefully. Breaking field changes require a new API version. The API’s path version is separate from the existing webhook envelope’s date-based version. No ETag, incremental synchronization or snapshot export is promised in the first release.

Caching and freshness

To protect the service, successful reads of events and ticket types are held at the network edge for up to 30 seconds. A response carries X-Edge-Cache:

ValueMeaning
MISSNot held. This response came from Stello and is now held.
HITServed from the edge. Age says how many seconds old it is.
BYPASSNever held: ticket checks, and anything that is not a plain read.

A held response is only ever given to the same key, for the same URL and query. A revoked key, a disabled organization or a changed permission can therefore take up to 30 seconds to show on a read that was already held. Ticket checks are never held, so they are always current. Errors are never held.

Requests the edge can see are invalid, such as a wrong method or a key that is not well formed, are refused there with the same error body Stello uses (405, 401). The rate limits above are also applied at the edge, so a client that exceeds them gets 429 with Retry-After without the request reaching Stello’s data service.