Errors

One shape, always.

{
  "error": {
    "code": "invalid",
    "message": "no value for guest_name",
    "hint": "A contract that ships with a placeholder still in it is worse than one that failed to send."
  }
}

The message is frequently the database's own sentence, passed through rather than replaced. It is more specific than anything this layer could write, and the layer that knows why something was refused is the layer that refused it.

Retrying

Retry 429 and 500, with backoff. Do not retry 422 — the request will be refused the same way every time, and the message says why. Retrying anything that creates something means sending an idempotency key; our own SDK mints one for you.

402 is not 429

A 402 means the account needs money or the membership, not a pause: Free's 10 signings are used, the prepaid credit has run out, or the business's own spending limit is reached. It is the one refusal that a retry cannot fix: credit has to be added (automatic reload usually does it first), the membership started, or the month has to turn. Treat it as you would a declined card — surface it to the person who can act on it, and stop. The response carries the same shape as any other error, and the hint names the way out.

One start is answered otherwise: a counter tablet's, made with no network and sent when it synced. The person has already signed at the counter, so the answer is 429 allowance_reached, for the tablet to keep it and send it again. Nothing is made until the business can take another signing, and then it counts like any other.

Every successful send carries x-agreements-remaining when the account has a fixed number of signings left to count down: how many more documents it can send before it needs credit. A document out for signature holds its place, so the number goes down with the send that sent it, and comes back if that document is voided, declined or expires unsigned; one that is never signed costs nothing. It is on the send's answer because that is the call an integration already makes. It is absent when there is nothing to count down. Watch it and you will never meet a 402 unprepared — or subscribe to billing.quota_approaching and do not watch at all.

A 429 carries Retry-After, in seconds. Wait that long rather than backing off by a guess: the rate-limit window is a minute, so three quick retries all land inside the same window, fail identically, and spend the next window's budget as well. The Node client honors the header — it sleeps through a short wait and hands a long one back to you as error.retryAfter rather than blocking your call for a minute.