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).

Common codes

Authentication / authorization

Status	Code	When
401	`invalid_key`	Bearer token missing, malformed, or revoked.
402	`tier_required`	Workspace not on a tier with API access (or monthly cap reached).
404	`not_found`	Resource doesn't exist, OR belongs to a different workspace.

Request shape

Status	Code	When
400	`invalid_request`	Body validation failed (zod-style message in `error`).
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 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`.
422	`placement_failed`	pdf-lib threw while masking anchors / appending the signature page.
501	`placement_not_implemented`	Reserved — currently unused.

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 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`	Tried to download `signed.pdf` or `audit-trail.pdf` before every signer signed.
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).

Rate limiting + storage

Status	Code	When
429	`rate_limited`	60 requests/minute/key exceeded. Retry after the `Retry-After` header.
500	`storage_failed`	Blob upload 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.letssign.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