Errors

Errors are JSON-bodied with a stable code string and a human-readable error message. The error is for humans (logs, dashboards, oncall chat) and may improve over time. The code is for code — pin your catch logic to that.

{
  "error": "Signer with role \"tenant\" has no [[ls:...:tenant]] anchor in the PDF",
  "code":  "signer_has_no_anchor",
  "meta":  { "role": "tenant" }
}

meta carries structured context when relevant (which role failed, which signer carried an unknown key, etc). A few codes carry their context at the top level instead of inside meta:

A success body can carry warnings: [{ field, code, message }] — see Warnings below.

Common codes

Authentication / authorization

Request shape

Fetching file_url

POST /v1/signing-requests with a file_url fetches the PDF before anything else happens. Nothing is created when the fetch fails.

Placement

A PDF with no markers is never an error, whether you passed placement="anchors" or left the default: the call falls through to an appended signature page and the response says "placement": "auto_append" with anchors.found: 0. Check those two fields if a missing marker must stop your workflow — see Anchor placeholders.

Idempotency

See Idempotency for the full retry-safe pattern.

Signing requests: remind, withdraw, correct the phone

Documents: downloads

Templates

Confirm and discard

Problem codes of template_input_invalid

Each entry of problems[] is { field, label, code, message, allowed? }:

The same body's warnings[] can carry unknown_field and unknown_column (below); they never cause the 422 on their own.

Embedded signing

ttl_seconds outside 60–900 and an unknown locale are refused as 400 invalid_request rather than silently clamped or defaulted. See Embedded signing.

Webhook subscriptions

Retired endpoints

Rate limiting + storage

Codes outside an HTTP error

Some codes reach you on a 200 or outside the HTTP response altogether:

• problems[].code on a validate_only 200 — sms_allowance_exhausted when a dry run of instantiate finds the SMS allowance short (with ok: false). A dry run whose field_values fail still answers 422 template_input_invalid, like the real call. See SMS verification.
• reason on signing_request.sms_failed — invalid_number, landline, blocked, rate_limited, allowance_exhausted, not_configured, provider_error. See Webhooks.
• detail on the embedded frame's wesign.error message — not_found, revoked, key_revoked, unavailable, withdrawn, queued, sms_required (a before_view signer, who cannot verify inside a frame yet), sign_failed, sealing_in_progress, pades_failed, seal_persist_failed or http_<status>. See Embedded signing.

Warnings

A 2xx body — and the 422 template_input_invalid — may carry warnings: [{ field, code, message }]. A warning never fails the call, but each one names something that did not happen the way you probably meant:

Log them, and alert on them in your integration tests.

Detecting an error in code

async function send(opts) {
  const res = await fetch('https://api.wesign.now/v1/signing-requests', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.WSK_KEY}` },
    body: opts.formData,
  })
  if (!res.ok) {
    const body = await res.json()
    if (body.code === 'idempotency_in_progress') {
      const retryAfter = Number(res.headers.get('retry-after')) || 5
      await sleep(retryAfter * 1000)
      return send(opts) // retry the SAME idempotency key
    }
    if (body.code === 'rate_limited') {
      const retryAfter = Number(res.headers.get('retry-after')) || 60
      await sleep(retryAfter * 1000)
      return send(opts)
    }
    if (body.code === 'tier_required') {
      // The plan's monthly document cap is reached.
      throw new UpgradeRequiredError(body.meta?.tier, body.meta?.cap, body.meta?.used)
    }
    if (body.code === 'sms_allowance_exhausted') {
      // Nothing was created. Top-level, not under meta.
      throw new SmsAllowanceError(body.sms_allowance.remaining, body.required, body.sms_allowance.resets_at)
    }
    throw new ApiError(body.code, body.error, res.status)
  }
  return res.json()
}