From 8eff95908f9d0d06369aad0e9d434843d29f334e Mon Sep 17 00:00:00 2001 From: Nicolas Fry Date: Mon, 5 Oct 2026 17:45:01 -0400 Subject: [PATCH] docs(turbosign): document error status codes for single-step and update-with-recipients Rebased onto develop: moved from the old space-named paths to API-Signatures.md and embedded-signing/reference.md, and noted that DocumentNotFound/RecipientNotFound moved from 400 to 404 in v1.132.0. --- docs/TurboSign/API-Signatures.md | 30 ++++++++++++++++++++ docs/TurboSign/embedded-signing/reference.md | 2 +- 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/TurboSign/API-Signatures.md b/docs/TurboSign/API-Signatures.md index 148cddc..5337246 100644 --- a/docs/TurboSign/API-Signatures.md +++ b/docs/TurboSign/API-Signatures.md @@ -2160,6 +2160,36 @@ formData.Add(new StringContent(recipients), "recipients"); | `429` | Too Many Requests | Implement rate limiting and retry logic | | `500` | Internal Server Error | Contact support if persistent | +### Error Codes for Sending and Updating Recipients {#error-codes-for-sending-and-updating-recipients} + +`POST /turbosign/single/prepare-for-review`, `POST /turbosign/single/prepare-for-signing` and `PATCH /turbosign/documents/{id}/update-with-recipients` return signature errors with a specific HTTP status and a machine-readable code. The body includes `error` (human-readable text) and `code` (the machine-readable value). It also repeats them as `message` and `type`, and may include a `data` object with details, so read the fields you need and ignore the rest: + +```json +{ + "message": "This organization does not allow changing the identity-verification method. Omit otpChannel or set it to 'email'.", + "type": "OtpOverrideNotAllowed", + "error": "This organization does not allow changing the identity-verification method. Omit otpChannel or set it to 'email'.", + "code": "OtpOverrideNotAllowed" +} +``` + +| Status | `code` | Meaning | +| ------ | ------ | ------- | +| `400` | Any `code` not listed below, for example `OtpPhoneRequired`, `OtpPhoneInvalid`, `IdentityConfigInvalid`, `DuplicateExternalId` | The request is invalid. Fix the input and retry. | +| `402` | `OtpNotEntitled`, `SmsOtpLimitExceeded` | The plan does not include this verification, or the SMS allowance is used up. | +| `403` | `ExternalIdvNotAllowed`, `IdentityOverrideNotAllowed`, `OtpOverrideNotAllowed`, `EmbeddedSigningNotEnabled`, `SmsOtpNotEnabled` | The organization has not turned on the feature or mode the request uses, or has locked the passcode method. | +| `404` | `DocumentNotFound`, `RecipientNotFound` | The document or recipient does not exist, was deleted, or belongs to another organization. On `update-with-recipients`, a document ID that does not exist returns `404` with only `{ "error": "Document not found" }`. | +| `409` | `DocumentNotSignable`, `RecipientAlreadySigned`, `RecipientNotInTurn`, `NotSignersTurn`, `SmsProviderNotConfigured`, `RecipientRequiresSingleUseUrl` | The document or recipient is not in a state that allows the request, or the organization has no SMS provider saved. | +| `410` | `SigningUrlNotRedeemable` | A single-use signing URL was already used or has expired. | + +None of these signature errors return a `5xx` status. A `500` from these endpoints means an unexpected server problem, not a problem with your request. + +:::note Changed in v1.132.0 +`DocumentNotFound` and `RecipientNotFound` returned `400` from these endpoints before v1.132.0. Since v1.132.0 they return `404`. If your integration checks for `400` to detect a missing document or recipient, check for `404` or read `code` instead. +::: + +For what each identity and passcode code means and how to fix it, see [Embedded signing errors](./embedded-signing/reference.md#errors). + ### Common Issues #### JSON String Formatting Errors diff --git a/docs/TurboSign/embedded-signing/reference.md b/docs/TurboSign/embedded-signing/reference.md index 73f4575..f7363de 100644 --- a/docs/TurboSign/embedded-signing/reference.md +++ b/docs/TurboSign/embedded-signing/reference.md @@ -536,7 +536,7 @@ Identity and passcode errors from sending a document and from `createSigningUrl` | 410 | `SigningUrlNotRedeemable` | A single-use signing URL was already used or has expired. Request a new one. | | 423 | `locked` | The signer entered 20 wrong codes. See [Passcode attempts and lockout](#passcode-attempts-and-lockout). | -A missing document returns `404` with the older `{ "message", "type": "DocumentNotFound" }` body. The signer-facing passcode endpoints that the signing page calls use their own `{ "error", "code" }` body with lowercase codes, for example `locked` with HTTP `423`. +A missing document returns `404` with `DocumentNotFound`. When you send a document, that error uses the same four-field body as above; other endpoints may return only `message` and `type`. See [Error Codes for Sending and Updating Recipients](../API-Signatures.md#error-codes-for-sending-and-updating-recipients) for the full list for those endpoints. The signer-facing passcode endpoints that the signing page calls use their own `{ "error", "code" }` body with lowercase codes, for example `locked` with HTTP `423`. :::warning A blank iframe is not an API error When your origin is not under **Allowed embedding domains**, the API calls all succeed but the browser refuses to render the frame (a `frame-ancestors` error in the console). Add your origin in [Set up your organization](./set-up-your-organization.md#step-5-allow-the-origins-that-may-embed-the-signing-page).