Going to production

The quickstart gets one envelope signed. This page covers what changes when real traffic arrives: how to page through results, what happens when you hit a limit, and the handful of decisions worth making before your first customer signs something.

Pagination

List endpoints take limit and offset. limit defaults to 25 and is capped at 100 — a larger value is rejected rather than silently clamped, so a request that asks for too much fails loudly instead of quietly returning a short page.

curl 'https://api.sign.quathos.com/api/v1/envelopes?limit=25&offset=0&status=sent' \
  -H 'Authorization: Bearer $QUATHOS_SIGN_TOKEN'

Responses carry the page in items and the full count under the same filters in total, so you can paginate without fetching everything first:

{
  "items": [ /* … */ ],
  "total": 137,
  "limit": 25,
  "offset": 0
}

let offset = 0;
const limit = 100;               // maximum accepted
const all = [];

for (;;) {
  const res = await fetch(
    `https://api.sign.quathos.com/api/v1/envelopes?limit=${limit}&offset=${offset}`,
    { headers: { Authorization: `Bearer ${process.env.QUATHOS_SIGN_TOKEN}` } }
  );
  const page = await res.json();
  all.push(...page.items);
  offset += limit;
  if (offset >= page.total) break;
}

Rate limits

Limits protect the endpoints that are exposed to the open internet or that cost money to serve: authentication, the signing flow, public verification, public signing links, checkout, member invitations and voucher redemption. When you exceed one, the response is 429 with detail: "rate_limited" and a Retry-After header giving the seconds until the window resets.

Pre-launch checklist

• Use a test token in every environment that is not production

  The environment is baked into the token prefix and cannot be changed after creation. A staging service holding a qsign_live_ token will email real signers. Authentication.

• Send an Idempotency-Key on every write

  Generate it once per logical operation and reuse it on retries. Same key with a different payload returns 409 rather than silently creating a second envelope. Errors.

• Branch on the detail code, never on the message

  Codes are part of the contract; wording is not, and it may be localized. Error reference.

• Treat webhooks as the source of truth for state changes

  Polling the envelope endpoint on a timer works but wastes your rate budget and adds latency. Verify the signature and deduplicate on X-Webhook-Id. Webhooks.

• Back off on 429 using Retry-After

  The response carries the number of seconds until the window resets. Honor it instead of retrying immediately with a fixed delay.

• Store the envelope id, not just your own reference

  Every later call — status, evidence dossier, download — is keyed by it.

Not available yet

Worth knowing before you design around something that does not exist. When any of these ship, this section shrinks.

• No official SDKs. The API is REST; the examples throughout these docs are cURL, Node.js and Python, and the client code is yours to write.
• No embedded signing. Signers sign on a link we host, carrying your customer’s branding. There is no iframe or drop-in component for signing inside your own application.
• No cursor pagination. Offset paging is stable enough at current page sizes, but a resource created mid-iteration can shift rows between pages. If exactness matters, filter by a fixed status or narrow the window.