Pagination, errors & rate limits

Lists and pagination

List endpoints return:

{
  "data": [ ... ],
  "page": { "next_cursor": "a2V5c2V0…", "has_more": true, "total": 132 }
}

Pass ?limit= (1–100, default 25) and ?cursor= with the previous page's next_cursor. Cursors are opaque; do not construct them. total is included where it is cheap to compute.

Ids

Money and time

Money is { "amount": "49.00", "currency": "AUD" } with a decimal string amount. Timestamps are ISO 8601 in UTC.

Errors

Errors are RFC 9457 problem details with Content-Type: application/problem+json:

{
  "type": "https://api.merchable.co/docs/errors#validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "errors": { "items.0.quantity": ["must be greater than 0"] },
  "request_id": "F-Ab12…"
}

Every type links to the matching section below (/docs/errors#<fragment>).

bad_request

400 — malformed request: invalid JSON, or a missing Idempotency-Key on POST /v1/orders.

unauthenticated

401 — missing, invalid, expired or revoked credential. The response carries a WWW-Authenticate challenge.

insufficient_scope

403 — the credential is valid but lacks the scope the operation needs (each operation in the reference lists it).

not_found

404 — no such resource in your account. Resources belonging to other accounts return the same 404.

conflict

409 — an Idempotency-Key replayed with a different body, or an order that can no longer be cancelled.

validation

422 — field errors (in the errors map) or a business rule the request breaks (in detail), such as a minimum order quantity or a declined card.

rate_limited

429 — see Rate limits below; retry after Retry-After seconds.

internal

5xx — retry with backoff and include request_id when contacting support.

Rate limits

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). A 429 also carries Retry-After.

Request ids

Every response has an X-Request-Id header (also in error bodies). Quote it when reporting a problem.