Authentication and Errors

The API key

Retail sends one header on every request:

X-API-Key: <the key Gomry issued you>

X-API-Key, not Authorization: Bearer. It is a plain shared secret, not an OAuth token. An integration that reads Authorization answers 401 to every call, and both sides’ unit tests still pass. Header names are case-insensitive, so x-api-key is the same header.

Gomry generates the key. It is 32 random bytes, delivered to you once over a secure channel. You never choose it, which lets us guarantee its strength and rotate it without asking you to redeploy code. Your integration must:

Fail closed. If no key is configured on your side, reject every request. An unset key must never mean “allow everyone”: POST /orders spends real money.
Compare in constant time, so a key cannot be guessed one character at a time.
Accept more than one key. During a rotation both the old and the new key are live for a while. A second key also lets you give a tester access without sharing Retail’s own.
Answer 401 for a missing or wrong key, with the error body below.

Node.js

import { timingSafeEqual } from "node:crypto";

const accepted = [process.env.GOMRY_RETAIL_API_KEY, process.env.GOMRY_RETAIL_API_KEY_NEXT]
  .map((k) => k?.trim())
  .filter(Boolean);

export function requireApiKey(request) {
  if (accepted.length === 0) throw unauthorized("API key is not configured");
  const presented = Buffer.from(request.headers.get("x-api-key") ?? "");
  const ok = accepted.some((key) => {
    const expected = Buffer.from(key);
    return expected.length === presented.length && timingSafeEqual(expected, presented);
  });
  if (!ok) throw unauthorized("Invalid or missing X-API-Key");
}

Error format

Answer every failure with a JSON body in this shape:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body: quantity Expected number, received string"
  }
}

message is for humans and goes into Retail’s logs. Never put a buyer’s email, address or a barcode in it.

Status	`code`	Use it when
`400`	`validation_error`	The request is malformed, or your system refused it in words (the price moved, the hold expired, a required field for this delivery format is missing).
`401`	`unauthorized`	The API key is missing or wrong.
`404`	`not_found`	You do not know the thing asked about. See each endpoint for what that means there.
`429`	`throttled`	Your system (or your supplier) is rate limiting. Include `Retry-After`.
`502`	`integration_error`	Your upstream call failed or timed out.
`500`	`internal_error`	Anything else.

404 has a meaning

Retail treats 404 as an answer, not a failure:

Listings: a listing that was bought disappears. It does not report quantity 0.
Fulfilment, credentials: you do not know this order yet.
Venue map: treated as “no map”.

Every other non-2xx status is a failure, and Retail never treats a failure as “nothing there”.

429 pauses Retail’s calls to you

When you answer 429, Retail pauses its page-render and background calls to you, from every instance, until the time you give. Checkout calls still go through, so a buyer who is paying is not stranded by a catalog sync. Give the time in either of these forms. Retail reads them in this order:

A Retry-After header, in seconds or as an HTTP date.
error.retryAfter in the body, as an ISO 8601 timestamp.

Without either, Retail assumes you will take calls again after the current minute.

429

{
  "error": {
    "code": "throttled",
    "message": "Rate limit reached",
    "retryAfter": "2026-09-30T18:53:00Z"
  }
}

If your supplier limits calls per application, across all endpoints, say so when you go live. Retail keeps a shared per-minute budget per supplier and gives checkout and buyer-facing calls priority over background sync.

Do not retry inside a call

Your integration must not retry internally on any endpoint. Retries belong to Retail, because only Retail knows whether an operation is safe to repeat:

On listings, a slow success is worse than a fast failure. The buyer’s page has already given up and rendered the event as unavailable.
On place order, a retry can buy the ticket twice. See Place order.

Time budgets

Retail aborts a call after these limits. A reply after the limit is discarded.

Call	Limit	Why
Listings, while a page renders	4.5 seconds	A buyer is waiting on the page.
Listings, background refresh	12 seconds	Warms Retail’s cache ahead of buyers.
Catalog page	30 seconds	Scheduled sync. Size your pages to fit.
Quote, place order, credentials	20 seconds	Checkout and delivery to the buyer.
Search orders, fulfilment	25 seconds	Background reconciliation and delivery polling.

A timed-out POST /orders is not a failure to Retail. It is an unknown outcome, resolved by searching for the reference.

Overview

Catalog and Listings

Purchasing

Delivery

Authentication and Errors

Authentication and Errors

The API key

Error format

404 has a meaning

429 pauses Retail’s calls to you

Do not retry inside a call

Time budgets

​Authentication and Errors

​The API key

​Error format

​404 has a meaning

​429 pauses Retail’s calls to you

​Do not retry inside a call

​Time budgets

Authentication and Errors

The API key

Error format

404 has a meaning

429 pauses Retail’s calls to you

Do not retry inside a call

Time budgets