Making requests

This page covers the conventions shared by every endpoint: the response envelope, the error-code catalog, idempotency, and pagination.

The response envelope

Every response — success or failure — is a JSON object with exactly three top-level keys:

{
  "data":  { },
  "error": null,
  "meta":  { "request_id": "req_9f2c1a" }
}

• meta.request_id is present on every response. Log it — it is the fastest way for support to trace a request.
• meta.next_cursor appears only on paginated list responses (see Pagination).

A failure looks like:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields failed validation.",
    "details": { "fields": [{ "field": "amount", "message": "must be a positive integer" }] }
  },
  "meta": { "request_id": "req_9f2c1a" }
}

Always branch on the HTTP status and error.code — never parse error.message, which is human-facing and may change.

Error-code catalog

These are the codes the platform returns, with their HTTP status. They are the single source of truth from libs/common/src/http/errors.ts.

Notes:

• 429 responses include a Retry-After header with the number of seconds to wait.
• The error.code enum published in the OpenAPI reference lists the nine codes you can receive on documented endpoint responses; PERMISSION_DENIED and INTERNAL_ERROR are platform-wide codes that can also occur.

Idempotency

Fund-moving and resource-creating POSTs require an Idempotency-Key header: a client-generated string unique to one logical operation (a UUID v4 is ideal).

Idempotency-Key: 3f9a1c2e-...

Semantics

• First time a key is seen — the request runs normally and its result is stored against the key.
• Same key + identical payload — the stored original result is returned without re-executing. The status is 200 and the effect is not duplicated. This makes retries after a network timeout safe.
• Same key + different payload — rejected with 409 IDEMPOTENCY_CONFLICT. A key is bound to the exact payload it was first used with (compared by a canonical, key-sorted SHA-256 hash of the body).

Keys are scoped to your merchant, so they never collide with another merchant's.

Where it is required

The header is required on:

GET requests never take an idempotency key. POST /split-rules and POST /fx/rate-locks do not require one (they are naturally re-runnable / not fund-moving).

Retry pattern

const key = crypto.randomUUID();
async function createWithRetry(body) {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await post('/collections', body, { 'Idempotency-Key': key }); // same key every attempt
    } catch (e) {
      if (attempt === 2 || !isTransient(e)) throw e;      // 5xx / network only
      await sleep(250 * 2 ** attempt);
    }
  }
}

Reuse the same key across every retry of the same logical attempt; generate a new key for a genuinely new operation.

Pagination

List endpoints use opaque cursor pagination — never numeric offsets.

Request:

GET /transactions?limit=50&cursor=<opaque>

• limit — page size, 1–100, default 50. Out-of-range values are clamped.
• cursor — omit for the first page; then pass the previous response's meta.next_cursor.

Response:

{
  "data": [ /* up to `limit` items */ ],
  "error": null,
  "meta": {
    "request_id": "req_9f2c1a",
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0xNVQwOToxNTowMFoiLCJpZCI6IjNmYTg1ZjY0In0"
  }
}

Keep following next_cursor until it comes back null, which means there are no more pages. The cursor is a base64url token; treat it as opaque and pass it back unchanged.

let cursor = undefined;
do {
  const q = new URLSearchParams({ limit: '50', ...(cursor ? { cursor } : {}) });
  const res = await get(`/transactions?${q}`);
  for (const tx of res.data) handle(tx);
  cursor = res.meta.next_cursor;      // string, or null when done
} while (cursor);