Errors
Every error code the Esign Comply API returns, with its HTTP status and type, when it occurs and what to do.
Every error response has the same envelope. type is the class, code is the stable machine value, and message says what happened, why, and the fix. The doc_url in each error points at the code's entry on this page.
{
"error": {
"type": "ceremony_error",
"code": "steps_incomplete",
"message": "The ceremony is missing 2 required steps: notice.captured, intent.captured.",
"missing_steps": ["notice.captured", "intent.captured"],
"doc_url": "https://esigncomply.com/docs/api/errors#steps_incomplete",
"request_id": "req_8Yb2kQ0x"
}
}
Branch on type first, then on code. Within an API version the type list is closed and the code returned for a condition does not change. New codes may be added for new conditions, so treat a code you do not know as its type. The envelope fields are described on API conventions.
All codes
| Code | HTTP | Type |
|---|---|---|
invalid_request |
400 | invalid_request_error |
jurisdiction_unknown |
400 | invalid_request_error |
missing_api_key |
401 | authentication_error |
invalid_api_key |
401 | authentication_error |
client_token_expired |
401 | authentication_error |
quota_exhausted |
402 | quota_error |
quota_exceeded |
402 | quota_error |
storage_limit_reached |
402 | quota_error |
certificate_charge_unconfirmed |
402 | billing_error |
certificate_spend_limit_reached |
402 | billing_error |
payment_method_required |
402 | billing_error |
domain_not_verified |
403 | permission_error |
domain_mismatch |
403 | permission_error |
insufficient_permission |
403 | permission_error |
plan_feature_unavailable |
403 | permission_error |
signer_certificates_disabled |
403 | permission_error |
not_found |
404 | invalid_request_error |
subject_not_found |
404 | invalid_request_error |
idempotency_conflict |
409 | conflict_error |
step_out_of_order |
409 | conflict_error |
session_not_active |
409 | conflict_error |
domain_already_registered |
409 | conflict_error |
record_not_timestamped |
409 | conflict_error |
baseline_unchanged |
409 | conflict_error |
rollback_unavailable |
409 | conflict_error |
region_mismatch |
421 | invalid_request_error |
steps_incomplete |
422 | ceremony_error |
conformance_failed |
422 | conformance_error |
render_mismatch |
422 | ceremony_error |
document_type_excluded |
422 | ceremony_error |
verification_failed |
422 | ceremony_error |
version_not_published |
422 | ceremony_error |
jurisdiction_not_enabled |
422 | ceremony_error |
signer_region_required |
422 | ceremony_error |
jurisdiction_fact_required |
422 | ceremony_error |
certificate_set_too_large |
422 | invalid_request_error |
certificate_field_unavailable |
422 | invalid_request_error |
file_type_refused |
422 | invalid_request_error |
file_hash_mismatch |
422 | invalid_request_error |
file_too_large |
422 | invalid_request_error |
rate_limit_exceeded |
429 | rate_limit_error |
test_quota_exceeded |
429 | rate_limit_error |
internal_error |
500 | api_error |
service_unavailable |
503 | api_error |
certificate_verification_failed |
503 | api_error |
Request errors
invalid_request
400 · invalid_request_error
When. The request is malformed: the body is not valid JSON, a known field has the wrong type, a required field is missing, a value is out of range, or a limit was passed (for example metadata over 50 keys, context.extra over 16 KB, event data over 256 KB, an Idempotency-Key over 255 characters, an unknown Esign-Comply-Version). It is also returned when a profile uses explicit jurisdiction mode and the session sends no jurisdictions.packs, and when a supplement would pass the limit of 200 per record.
What to do. Read param: it names the field. Fix the request and send it again. Do not retry unchanged. Unknown fields are never the cause: they are ignored and reported as unknown_field:<path> warnings.
jurisdiction_unknown
400 · invalid_request_error
When. A pack code on a profile, a session, a dry run or a certificate wording is not in the catalogue.
What to do. Read the catalogue from GET /v1/jurisdictions and use a code from it. Do not hard-code the list. A U.S. state without a pack is not an error when it arrives as signer.region: the session runs on the Federal pack with the warning state_pack_unavailable:<code>. See Jurisdiction packs.
not_found
404 · invalid_request_error
When. No object with that ID exists in this domain and environment. A test key cannot see live objects and a live key cannot see test objects. A client token gets not_found for any session other than its own and for a document version that is not pinned on its session. A voided or erased record also returns not_found.
What to do. Check the ID, the environment of the key (esc_test_ or esc_live_) and the domain the key belongs to. In server confirmation, treat not_found as "no such record": do not grant access.
subject_not_found
404 · invalid_request_error
When. A supplement names a record, session, signer or document version that does not exist in this domain and environment, references a file ID that does not exist, or names a supersedes target that does not exist. Also returned when a consent withdrawal is sent for a signer who has no record.
What to do. Send exactly one existing subject, or omit subject to attach the supplement to the domain. Create the file with POST /v1/files before referencing it. See Supplements and files.
region_mismatch
421 · invalid_request_error
When. The key belongs to the other region. A key works only against the region of its domain.
What to do. Send the request to the host in the error object.
{
"error": {
"type": "invalid_request_error",
"code": "region_mismatch",
"message": "This key belongs to the EU region. Use api.eu.esigncomply.com.",
"host": "api.eu.esigncomply.com",
"region": "eu",
"doc_url": "https://esigncomply.com/docs/api/errors#region_mismatch",
"request_id": "req_8Yb2kQ0x"
}
}
The server SDK picks the host from the region code in the key, so this error usually means a hard-coded base URL.
Authentication errors
missing_api_key
401 · authentication_error
When. The request has no Authorization header, or the header is not Bearer <credential>.
What to do. Send Authorization: Bearer esc_test_us_... from your server. In a browser, send the session client token, never a secret key.
invalid_api_key
401 · authentication_error
When. The secret key is not valid or has been revoked, or the session client token is malformed or was not issued by Esign Comply. On the agent account API: the agent token is wrong, expired or revoked, or an API key was sent where an agent token is needed. The message says which.
What to do. Check that the environment variable holds the whole key and that the key has not been revoked. If a key may have been exposed, revoke it and create a new one. See /auth.md.
client_token_expired
401 · authentication_error
When. The session client token has expired, or the session reached its lifetime (30 minutes by default) before the ceremony was completed. Events, verifications and completion all return this code for an expired session.
What to do. Create a new session on your server and attach again with the new client_token. Use a new Idempotency-Key: the old key would replay the expired session. Start the ceremony when the form is shown, not when the page first loads in a background tab.
Permission errors
domain_not_verified
403 · permission_error
When. A live key is used before its domain is verified, or domain verification lapsed more than 14 days ago and the request tries to create a live session. Also returned when a live key is requested for a domain that is not verified.
What to do. Publish the verification record shown for the domain (a DNS TXT record named _esigncomply with the value esc-verify=<token>, or the file /.well-known/esigncomply.txt on a platform host), or use a test key on localhost. Existing records are not affected by a lapse. See Register a domain.
domain_mismatch
403 · permission_error
When. In live mode, context.url on a session or the Origin of a browser call is outside the registered domain, or a live browser call carries no Origin. In test mode, the URL or origin is not localhost, 127.0.0.1, the registered domain or a listed preview host.
What to do. Run the ceremony on the registered domain or one of its subdomains. For test keys, add the preview host to the domain's test origins. A move to a different registrable domain is a domain change. See Test mode.
insufficient_permission
403 · permission_error
When. The key's permission does not allow the call (for example a recording_access key asking for an evidence report), a secret key was sent to a browser-only endpoint, a client token was sent to a server-only endpoint, or a secret key tried to send ceremony events or the signing act for a session that was not created with capture_mode: "server_only".
On the agent account API it also means the step is the account owner's: the message ends with "This step needs the account owner in person." and the error carries needs_person: true.
What to do. The message names the permission and the capability needed. Use a key with that permission for the job, and keep the application key at recording_access. Ceremony events come from the signer's browser with the client token. The permission table is on API conventions. For a step that is the account owner's, tell the person which step it was.
plan_feature_unavailable
403 · permission_error
When. The feature is not on the domain's plan: a profile at L3 on Free or Starter, more webhook endpoints than the plan includes, SMS codes on a plan that has none or with the SMS verification allowance used up, a certificate request or quote for a live record on Free, a region the plan does not offer, or a custodian-signed certification on a plan or environment that does not have it.
On POST /v1/sessions in live mode the code means one of three things:
- The subscription was canceled.
- The domain is in a region the plan does not include. The Free plan records live in the US region only.
- The profile's assurance level is not on the plan.
It does not mean that a paid subscription is missing. The Free plan records live.
What to do. Change the request to something the plan includes (for example email_otp instead of sms_otp, or L2 instead of L3), or upgrade. After a cancellation, choose a plan under Settings, Billing in the dashboard. Plans are listed at /pricing.md.
signer_certificates_disabled
403 · permission_error
When. A signer requested a certificate and the customer has not turned signer requests on for the profile.
What to do. Nothing in a current integration can cause this code. It belongs to signer-requested certificates, which are planned for a later version. See Certificates.
Conflict errors
idempotency_conflict
409 · conflict_error
When. The Idempotency-Key was already used on this path with a different body, or a request with the same key is still in progress (then Retry-After: 1 is set). Publishing a document version returns this code when the same version_label and language already exist for the document: published versions are immutable.
What to do. For a retry of the same action, send the same body with the same key. For a new action, use a new key. For a document, publish under a new version_label.
step_out_of_order
409 · conflict_error
When. A ceremony event arrived before a step it depends on: any event before client.attached, access.demonstrated before disclosure.presented, econsent.given before the two steps before it, renewal_consent.captured before renewal_terms.presented, intent.captured before the documents and the notice were recorded, or a passkey step before the signer's email or phone was verified in the session. The error carries missing_steps.
What to do. Record the steps in missing_steps first. In the browser SDK, call EsignComply.attach() before anything else and let ceremony.remainingSteps() drive the interface. See The ceremony.
session_not_active
409 · conflict_error
When. The session is completed or cancelled, so it accepts no more events, verifications, completion or cancel. A second completion returns this code with the record_id of the record that already exists. It is also returned when the signer's data was erased while the session was open.
What to do. For a completed session, read record_id and confirm that record on your server. Do not ask the signer to act again. For a cancelled session, create a new one.
domain_already_registered
409 · conflict_error
When. The domain is attached to another active subscription. A domain can belong to only one.
What to do. If you own the domain, start a claim in the dashboard and publish the verification record to take it over. Otherwise register the domain you control.
record_not_timestamped
409 · conflict_error
When. A certificate was requested for a record whose external timestamp is not attached yet. Certificates need a record in timestamped or anchored status. Retry-After is set.
What to do. Wait for the interval in Retry-After and send the request again, or wait for the record.timestamped webhook. The timestamp normally follows completion within about a minute.
baseline_unchanged
409 · conflict_error
When. POST /v1/profiles/{id}/adopt was called and the profile has no record conditions waiting for adoption.
What to do. Nothing. Read pending_conditions on GET /v1/profiles/{id} before calling adopt. See Guidance and adoption.
rollback_unavailable
409 · conflict_error
When. POST /v1/profiles/{id}/rollback was called and there is no earlier baseline to return to, or the 90-day rollback window after the adoption has passed.
What to do. Nothing can be rolled back. To stop a state pack applying, remove the pack from the profile: sessions then proceed under the remaining packs with the warning jurisdiction_not_enabled:<code>.
Ceremony errors
steps_incomplete
422 · ceremony_error
When. POST /v1/sessions/{id}/complete was called before every required step was recorded. The error carries missing_steps, taken from the session's required_steps. It is also returned when a typed-name signature has no typed name.
What to do. Record the missing steps, then complete. For example, a session that still needs notice.captured and intent.captured: call ceremony.observeAssent() and have the signer perform the required action before calling ceremony.complete(). Keep the action control disabled until ceremony.remainingSteps() contains only signature.applied.
conformance_failed
422 · conformance_error
When. In live mode, a conformance rule at Block level that the profile has adopted did not pass, so the record is not sealed. The error carries rule (for example CR-01) and findings, each with a message, a measurement and a fix. Test mode never returns this code: it reports every finding and still seals.
What to do. Apply the fix of each finding to the interface, then have the signer act again. Do not retry automatically. Run the ceremony with a test key to see every finding before going live. Each rule is described on Conformance rules. Findings describe measurable design facts. They are not a statement that a flow is lawful or enforceable.
render_mismatch
422 · ceremony_error
When. In live mode, a document.presented event reported text that does not match the registered version (rule CR-08): the inline text has a different render_hash, or the page behind the link does. The event is kept as evidence of what the page presented.
What to do. Render the registered version, fetched from Esign Comply by its version ID, unmodified. Inject the html returned by the content endpoint as it is. If the text really changed, publish it as a new version. Do not copy document text into your repository. See Documents.
document_type_excluded
422 · ceremony_error
When. The exclusion screen of an applied pack blocks the document category, for example a will or a family-law document. The error carries rule, the exclusion ID, the pack and the reason.
What to do. Do not run this document through the ceremony. The blocked categories are listed for each pack under Jurisdiction packs and on What we do not cover.
verification_failed
422 · ceremony_error
When. A verification ended without success: the fifth wrong code (the session is then cancelled), a code that expired after 10 minutes, a fourth request for a message in one session, or an access-demonstration code that does not match the sample document. A single wrong code is not this error: the confirm call answers 200 with status: "failed" and attempts_remaining.
What to do. For an expired code, send a new one. After a lockout, create a new session. For the access demonstration, ask the signer to open the sample and type the code shown inside it. See L2 verification.
version_not_published
422 · ceremony_error
When. A session asked for version: "current" of a document that has no published version, or whose only versions have an effective_at in the future.
What to do. Publish a version with POST /v1/documents/{id}/versions, or name an exact version ID. Check effective_at: a version takes effect at that time, not at publication.
jurisdiction_not_enabled
422 · ceremony_error
When. The profile sets strict_jurisdictions: true and the session names a pack the profile does not enable. Without strict behavior this is not an error: the session proceeds with the warning jurisdiction_not_enabled:<code>.
What to do. Enable the pack on the profile, or stop naming it on the session.
signer_region_required
422 · ceremony_error
When. The profile sets on_unknown_region: "reject", the signer is in the United States, and the session has no signer.region.
What to do. Supply signer.region from your form or account data as an ISO 3166-2 code, for example US-CA. Do not infer it from an IP address. To accept sessions without a state, set on_unknown_region to strictest or base_only.
jurisdiction_fact_required
422 · ceremony_error
When. A Block condition that the profile has adopted fired and needs a context.facts key that the session did not send. The error names the key and the rule ID.
What to do. Send the fact when you create the session. Each pack lists the keys it reads, with type and allowed values, under "Fact keys" on its page in the pack catalogue. Facts are asserted by you and are not verified by Esign Comply.
Certificate and file errors
certificate_set_too_large
422 · invalid_request_error
When. A set certificate covers more records than the plan allows in one request: 100 on Starter, 10,000 on Unlimited.
What to do. Narrow the filter, for example with created_after and created_before, and send several requests.
certificate_field_unavailable
422 · invalid_request_error
When. A certificate request asks to include a field that was not captured, for example include: ["network"] for a record made under EU minimal capture.
What to do. Remove the field from include.
file_type_refused
422 · invalid_request_error
When. An uploaded file is an executable or an archive that contains one.
What to do. Send the material in another form, such as a PDF, an image, or text in the supplement itself. See Supplements.
file_hash_mismatch
422 · invalid_request_error
When. The bytes stored at the file's upload_url do not match the sha256 declared in POST /v1/files. The file is marked rejected.
What to do. Create a new file with the SHA-256 of the exact bytes you will upload, then upload again. Compute the hash from the same buffer you send.
file_too_large
422 · invalid_request_error
When. A supplement file exceeds the plan's size limit (10 MB on Starter, 25 MB on Unlimited), a PDF document version exceeds 10 MB, or a text document version exceeds 4 MB.
What to do. Send a smaller file, or split it.
Quota and billing errors
quota_exhausted
402 · quota_error
When. A new live signature was requested past the plan's limit and was refused. The check runs on POST /v1/sessions in live mode and on a live deferred submission (POST /v1/records/deferred). The code and the fields are the same on Free and Starter. Sessions already created still complete.
- Free. Free covers 10 live signatures a month. If you use all 10 in a month, the account locks until you upgrade to a paid plan. It does not unlock at the start of the next month. Past the limit, new live signatures can be refused, so upgrade before you get there.
- Starter. Starter covers 2,000 live signature events a year. At 2,000 the account locks until you pay: upgrade to Unlimited, add an event pack, or renew. Past the limit, new live signatures can be refused, so upgrade before you get there. Each event pack bought that year adds 1,000 to the limit.
Unlimited and Enterprise have no limit and never return this code.
The agent account API returns the same code for a locked account: every /v1/agent call except GET /v1/agent answers 402 quota_exhausted with locked: true, locked_since, plan, plan_name, limit, period and upgrade_url, and changes nothing. GET /v1/agent keeps answering and reports the lock.
The error object carries the plan, the limit, the period and the time of the lock. On Free:
{
"error": {
"type": "quota_error",
"code": "quota_exhausted",
"message": "Live signatures are being refused for this domain. All 10 of the Free plan's live signatures for the month were used and the account is locked. It stays locked until you upgrade to a paid plan: https://esigncomply.com/dashboard/settings/billing. Sessions already created still complete.",
"plan": "sandbox",
"plan_name": "Free",
"limit": 10,
"period": "month",
"period_start": "2026-11-01T00:00:00.000Z",
"resets_at": null,
"locked_since": "2026-11-19T14:22:07.000Z",
"upgrade_url": "https://esigncomply.com/dashboard/settings/billing",
"doc_url": "https://esigncomply.com/docs/api/errors#quota_exhausted",
"request_id": "req_8Yb2kQ0x"
}
}
On Starter:
{
"error": {
"type": "quota_error",
"code": "quota_exhausted",
"message": "Live signatures are being refused for this domain. The 2,000 live signature events of this subscription year were used and the account is locked. It stays locked until you pay: upgrade to Unlimited, add an event pack, or renew: https://esigncomply.com/dashboard/settings/billing. Sessions already created still complete.",
"plan": "starter",
"plan_name": "Starter",
"limit": 2000,
"period": "year",
"period_start": "2026-03-01T00:00:00.000Z",
"resets_at": null,
"locked_since": "2026-11-12T09:41:30.000Z",
"upgrade_url": "https://esigncomply.com/dashboard/settings/billing",
"doc_url": "https://esigncomply.com/docs/api/errors#quota_exhausted",
"request_id": "req_8Yb2kQ0x"
}
}
The examples leave out two fields that the error also carries, used and open_sessions. The table describes them.
| Field | Meaning |
|---|---|
plan, plan_name |
The plan id, sandbox or starter. sandbox is the id of the Free plan. plan_name is the name a person reads. |
limit |
The plan's limit for the period: 10 on Free, 2000 plus 1,000 for each event pack bought that year on Starter. |
used |
Live signature events completed in the period, at the time of the request. A true count; can be higher than limit. |
open_sessions |
Live sessions that are open and not expired, at the time of the request. A true count; can be higher than limit. |
period |
month on Free, year on Starter. |
period_start |
The start of the period the events were counted in. |
resets_at |
null while the account is locked. A locked account gets no new allowance on its own. |
locked_since |
The time the lock was set. |
upgrade_url |
The billing page in the dashboard. |
What to do. Pay at upgrade_url. On Free, upgrade to a paid plan. On Starter, upgrade to Unlimited, add an event pack, or pay for renewal. Do not wait and do not retry in a loop: the lock does not lift on its own. To avoid the refusal, read events.used and events.allowance from GET /v1/usage and upgrade before you reach the limit. See Free plan limits, Starter limits and /pricing.md.
quota_exceeded
402 · quota_error
When. An evidence report, an evidence package or a certificate was requested for a record that was locked under the earlier Starter quota rule. Such a record carries quota_locked: true. The record itself is sealed and its receipt still verifies. Records sealed now are not locked, on any plan.
What to do. Add an event pack, upgrade, or renew. All locked records unlock at once.
storage_limit_reached
402 · quota_error
When. The storage allowance for supplement files is used up. Text and JSON supplements are still accepted.
What to do. Send the report as text or JSON now, so that it is not lost, and upgrade or withdraw files you no longer need.
certificate_charge_unconfirmed
402 · billing_error
When. A certificate request would incur a charge and did not carry confirm_charge: true. Nothing is issued and nothing is charged. The error carries the quote.
{
"error": {
"type": "billing_error",
"code": "certificate_charge_unconfirmed",
"message": "This certificate costs $20.00. Resend the request with confirm_charge set to true to issue it.",
"quote": { "units": 1, "unit_amount": 2000, "amount": 2000, "currency": "usd", "allowance_remaining": 0, "month_to_date": 4000, "spend_limit": 20000 },
"doc_url": "https://esigncomply.com/docs/api/errors#certificate_charge_unconfirmed",
"request_id": "req_8Yb2kQ0x"
}
}
What to do. Show the quote to a person. Send the request again with confirm_charge: true only after that person approves. Never build a certificate request that can charge without a confirmation. See Certificates.
certificate_spend_limit_reached
402 · billing_error
When. The charge would pass the domain's monthly certificate spend limit ($200 by default). Nothing is issued.
What to do. An owner can change the limit in the dashboard, from $0 to $5,000. A limit of $0 switches paid certificates off.
payment_method_required
402 · billing_error
When. A charge would result and the domain has no valid payment method on file, or an earlier certificate invoice is unpaid.
What to do. Add or update the payment method in the dashboard. Recording, evidence reports and verification are not affected.
Rate limit errors
rate_limit_exceeded
429 · rate_limit_error
When. The key passed its per-second limit, a session passed 240 browser calls in a minute, or five set certificates are already being prepared for the domain. Retry-After is set.
What to do. Wait for the interval in Retry-After and retry. Space out batch jobs. The limits per plan are on API conventions.
test_quota_exceeded
429 · rate_limit_error
When. The month's allowance of test-mode events for the plan is used up, and a test session was requested.
What to do. Wait for the next calendar month, or move to a plan with a larger test allowance. Live recording is not affected.
Server errors
internal_error
500 · api_error
When. Something went wrong on Esign Comply's side.
What to do. Retry with the same Idempotency-Key, with backoff. For a completion, do not treat the agreement as signed and do not ask the signer to act again: reconcile the same session first with GET /v1/sessions/{id} and its record_id. Quote request_id to support if it persists.
service_unavailable
503 · api_error
When. A dependency is briefly unavailable: the receipt for a record is still being signed (GET /v1/records/{id}/receipt while the record is pending_seal), a verification message could not be sent, or SMS verification is not available.
What to do. Retry after Retry-After with the same Idempotency-Key. For SMS, fall back to email_otp.
certificate_verification_failed
503 · api_error
When. An integrity check failed while a certificate was being prepared. Nothing is issued, nothing is charged, an integrity incident is opened and certificate.failed is sent.
What to do. Do not retry. Contact support with the request_id.