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.

Every error says what was wrong and what to do next: which field, which id, which state. Log it whole. It never carries our own internals — when a 5xx is our failure (db_failed, storage_failed, render_failed, …) the message says so and what to retry, and the technical detail stays in our logs. Every answer under /v1 is JSON, including a path or a method that does not exist — see Unknown endpoints and methods.

{
  "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:

The meta of the common codes:

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

Common codes

Authentication / authorization

api_monthly_limit

402 on POST /v1/signing-requests once the documents your workspace created through the API this month reach your plan's cap:

• Free: 10 documents a month, the plan's own cap
• Branded: 100 documents a month through the API
• Enterprise: no cap

The body has the shape of tier_required: { "error": "…", "code": "api_monthly_limit", "meta": { "tier": "branded", "cap": …, "used": … } }. Nothing was created. Wait for the next month, or upgrade the plan (Pricing).

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: tags

A failed save is a 500 db_failed (nothing changed, retry) and a failed read a 503 temporarily_unavailable (retry after Retry-After), as below.

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

Unknown endpoints and methods

Every answer under /v1 — on api.wesign.now/v1 and /api/v1 on the app hosts — is JSON, a typo included. Neither needs a valid key, and neither counts against your rate limit.

{
  "error": "No endpoint GET /v1/signing. Did you mean GET /v1/signing-requests, GET /v1/signing-requests/{id} or POST /v1/signing-requests? Every endpoint is listed at https://www.wesign.now/docs/api-overview.",
  "code": "unknown_endpoint",
  "meta": {
    "method": "GET",
    "path": "/v1/signing",
    "did_you_mean": ["GET /v1/signing-requests", "GET /v1/signing-requests/{id}", "POST /v1/signing-requests"],
    "docs": "https://www.wesign.now/docs/api-overview"
  }
}

Before the 2026-10-11 release a path that did not exist answered an HTML page, and a wrong method an empty 405.

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, the 422s of ingest and placement on POST /v1/signing-requests and a 400 unknown_field — 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.WESIGN_API_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()
}