Errors

Stable error codes mapped to HTTP statuses. Pin your error handling to the code, not the human-readable message.

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 idempotency key collided, etc). The one exception is ip_not_allowed, which carries the observed caller address as a top-level ip field rather than inside meta — it is produced by the authentication layer, before any route-level meta exists.

Common codes

Authentication / authorization

Status	Code	When
401	`invalid_key`	Bearer token missing, malformed (neither `wsk_live_` nor `lsk_live_`), unknown, or revoked.
402	`tier_required`	Workspace not on a tier with API access, or the monthly document cap is reached (`meta.tier`, `meta.cap`, `meta.used`).
402	`enterprise-required`	The endpoint itself is Enterprise-only, whatever the plan's API access: template channels, QES, and minting embedded signing sessions. Sales-led — the message names the feature.
403	`ip_not_allowed`	The key is valid, but its IP allowlist is non-empty and the caller's address is not on it — or could not be determined. The body carries the address we saw as `ip` (`null` when unknown). An empty allowlist means unrestricted; see Restricting a key to your own IP addresses.
404	`not_found`	Resource doesn't exist, OR belongs to a different workspace than the key.

Request shape

Status	Code	When
400	`invalid_request`	Body validation failed (zod-style message in `error`) — including `phone_e164 is required when require_sms_verification is true`.
400	`invalid_idempotency_key`	`Idempotency-Key` header value not 1–255 ASCII-printable chars.
415	`unsupported_media_type`	Body is not `multipart/form-data` or JSON, or file is not `application/pdf`.
413	`file_too_large`	PDF exceeds 25 MB.

Placement

Status	Code	When
400	`unknown_role`	A field/anchor references a role no signer claims.
400	`signer_has_no_anchor`	A signer was passed but no anchor for their role exists in the PDF.
400	`duplicate_anchor`	Same signature/role appears twice on the same page.
400	`no_anchors_found`	`placement="anchors"` strict + the PDF has no extractable text or no markers. Switch to `auto_append` or `explicit`.
400	`placement_retired`	`placement="manual"` on `POST /v1/signing-requests` — retired 2026-07-31, refused before any document is minted. Use anchors, explicit coordinates or auto-append.
410	`placement_retired`	Any call to `POST /v1/documents` — retired 2026-07-31 with the manual flow; `file_url` on `POST /v1/signing-requests` covers ingest-by-URL.
422	`placement_failed`	pdf-lib threw while masking anchors / appending the signature page.

Idempotency

Status	Code	When
409	`idempotency_in_progress`	A previous call with the same `Idempotency-Key` is still processing. Retry after the `Retry-After` seconds.
422	`idempotency_key_reuse`	Same `Idempotency-Key` was used with a different request body. Use a fresh key.

See Idempotency for the full retry-safe pattern.

Manage + download endpoints

Status	Code	When
409	`invalid_state`	`remind`/`withdraw` rejected because the signing request is already signed/declined/withdrawn/expired.
409	`expired`	`remind` called on a request whose TTL has elapsed.
409	`not_complete`	`/signed` or `/audit-trail` requested before every signer signed. Wait for `document.completed`.
409	`not_stored`	Every signer signed but the sealed file is not on storage yet. Retry shortly.
404	`no_signers`	`/signed` on a document with no signers (a finalized file-only instance) — use `/pdf`.
502	`email_failed`	Resend or workspace SMTP errored while sending the reminder.
503	`email_not_configured`	The deployment doesn't have RESEND_API_KEY set yet (development only).

Templates

Status	Code	When
400	`missing_recipients`	`instantiate`: a slot that has fields was given no recipient (`meta.slots`).
404	`version_not_found`	`instantiate` pinned a `version` that has no snapshot (`meta.version`, `meta.current_version`).
422	`template_input_invalid`	One or more `field_values` failed validation; `problems[]` lists every one with its own `code` (`field_required`, `invalid_enum`, …). See Templates → Validation.
409	`not_staged` / `discarded` / `already_confirmed`	Confirm or discard called on an instance that is not (or no longer) staged.
410	`review_expired`	The 14-day review window closed.
422	`invalid_recipients`	Bad email, non-E.164 phone, SMS without a number, duplicate `signing_order` on confirm.
502	`render_failed`	The PDF could not be rendered on confirm; nothing was sent.
503	`review_unavailable`	Staging a generated file is not available on this deployment.

Embedded signing

Status	Code	When
400	`invalid_origin`	`origin` on `POST /v1/embedded/sign-sessions` is not a plain https origin — it carried a path, query, fragment, credentials or a wildcard, or used `http:`.
400	`origin_not_allowed`	The origin is well-formed but is not registered on this API key. Add it under Settings → API, "Allowed embed origins". The message lists what is registered.
409	`request_not_signable`	The signing request is not `pending`/`viewed`, or is past its own expiry, so there is nothing to frame.
503	`embedding_unavailable`	This deployment has not applied migration 0155 yet. Transient by definition — retry, or contact support.

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

Retired endpoints

Status	Code	When
410	`embedded_sessions_retired`	`POST /v1/embedded/sessions`. See Embedded signing.
410	`placement_retired`	`POST /v1/documents`.
400	`placement_retired`	`placement="manual"` on `POST /v1/signing-requests`.

Rate limiting + storage

Status	Code	When
429	`rate_limited`	60 requests per minute per API key exceeded. Retry after the `Retry-After` header.
500	`storage_failed`	Blob upload or download threw — most often a transient platform error, retry.
500	`db_failed`	Insert into `signing_requests` / `documents` errored. Surface to oncall; usually a schema-cache issue resolved by Supabase.

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 ${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') {
      throw new UpgradeRequiredError(body.meta?.tier, body.meta?.cap)
    }
    throw new ApiError(body.code, body.error, res.status)
  }
  return res.json()
}

On this page