# Errors

> Every error code the Esign Comply API returns, with its HTTP status and type, when it occurs and what to do.

Source: https://esigncomply.com/docs/api/errors

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.

```json
{
  "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](https://esigncomply.com/docs/api.md).

## All codes

| Code | HTTP | Type |
|---|---|---|
| [`invalid_request`](#invalid_request) | 400 | `invalid_request_error` |
| [`jurisdiction_unknown`](#jurisdiction_unknown) | 400 | `invalid_request_error` |
| [`missing_api_key`](#missing_api_key) | 401 | `authentication_error` |
| [`invalid_api_key`](#invalid_api_key) | 401 | `authentication_error` |
| [`client_token_expired`](#client_token_expired) | 401 | `authentication_error` |
| [`quota_exhausted`](#quota_exhausted) | 402 | `quota_error` |
| [`quota_exceeded`](#quota_exceeded) | 402 | `quota_error` |
| [`storage_limit_reached`](#storage_limit_reached) | 402 | `quota_error` |
| [`certificate_charge_unconfirmed`](#certificate_charge_unconfirmed) | 402 | `billing_error` |
| [`certificate_spend_limit_reached`](#certificate_spend_limit_reached) | 402 | `billing_error` |
| [`payment_method_required`](#payment_method_required) | 402 | `billing_error` |
| [`domain_not_verified`](#domain_not_verified) | 403 | `permission_error` |
| [`domain_mismatch`](#domain_mismatch) | 403 | `permission_error` |
| [`insufficient_permission`](#insufficient_permission) | 403 | `permission_error` |
| [`plan_feature_unavailable`](#plan_feature_unavailable) | 403 | `permission_error` |
| [`signer_certificates_disabled`](#signer_certificates_disabled) | 403 | `permission_error` |
| [`not_found`](#not_found) | 404 | `invalid_request_error` |
| [`subject_not_found`](#subject_not_found) | 404 | `invalid_request_error` |
| [`idempotency_conflict`](#idempotency_conflict) | 409 | `conflict_error` |
| [`step_out_of_order`](#step_out_of_order) | 409 | `conflict_error` |
| [`session_not_active`](#session_not_active) | 409 | `conflict_error` |
| [`domain_already_registered`](#domain_already_registered) | 409 | `conflict_error` |
| [`record_not_timestamped`](#record_not_timestamped) | 409 | `conflict_error` |
| [`baseline_unchanged`](#baseline_unchanged) | 409 | `conflict_error` |
| [`rollback_unavailable`](#rollback_unavailable) | 409 | `conflict_error` |
| [`region_mismatch`](#region_mismatch) | 421 | `invalid_request_error` |
| [`steps_incomplete`](#steps_incomplete) | 422 | `ceremony_error` |
| [`conformance_failed`](#conformance_failed) | 422 | `conformance_error` |
| [`render_mismatch`](#render_mismatch) | 422 | `ceremony_error` |
| [`document_type_excluded`](#document_type_excluded) | 422 | `ceremony_error` |
| [`verification_failed`](#verification_failed) | 422 | `ceremony_error` |
| [`version_not_published`](#version_not_published) | 422 | `ceremony_error` |
| [`jurisdiction_not_enabled`](#jurisdiction_not_enabled) | 422 | `ceremony_error` |
| [`signer_region_required`](#signer_region_required) | 422 | `ceremony_error` |
| [`jurisdiction_fact_required`](#jurisdiction_fact_required) | 422 | `ceremony_error` |
| [`certificate_set_too_large`](#certificate_set_too_large) | 422 | `invalid_request_error` |
| [`certificate_field_unavailable`](#certificate_field_unavailable) | 422 | `invalid_request_error` |
| [`file_type_refused`](#file_type_refused) | 422 | `invalid_request_error` |
| [`file_hash_mismatch`](#file_hash_mismatch) | 422 | `invalid_request_error` |
| [`file_too_large`](#file_too_large) | 422 | `invalid_request_error` |
| [`rate_limit_exceeded`](#rate_limit_exceeded) | 429 | `rate_limit_error` |
| [`test_quota_exceeded`](#test_quota_exceeded) | 429 | `rate_limit_error` |
| [`internal_error`](#internal_error) | 500 | `api_error` |
| [`service_unavailable`](#service_unavailable) | 503 | `api_error` |
| [`certificate_verification_failed`](#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](https://esigncomply.com/docs/guides/jurisdictions.md).

### `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](https://esigncomply.com/docs/api/supplements.md).

### `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.

```json
{
  "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](https://esigncomply.com/docs/api/agent.md#authentication): 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](https://esigncomply.com/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](https://esigncomply.com/docs/guides/domains.md).

### `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](https://esigncomply.com/docs/guides/test-mode.md).

### `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](https://esigncomply.com/docs/api/agent.md#what-stays-with-the-person) 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](https://esigncomply.com/docs/api.md). 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](https://esigncomply.com/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](https://esigncomply.com/docs/api/certificates.md).

## 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](https://esigncomply.com/docs/concepts/ceremony.md).

### `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](https://esigncomply.com/docs/guides/guidance.md).

### `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](https://esigncomply.com/docs/conformance.md). 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](https://esigncomply.com/docs/api/documents.md).

### `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](https://esigncomply.com/docs/jurisdictions.md) and on [What we do not cover](https://esigncomply.com/compliance/not-covered).

### `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](https://esigncomply.com/docs/guides/l2-verification.md).

### `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](https://esigncomply.com/docs/jurisdictions.md). 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](https://esigncomply.com/docs/guides/supplements.md).

### `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](https://esigncomply.com/docs/api/agent.md#when-the-account-is-locked) 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:

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

```json
{
  "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`](https://esigncomply.com/docs/api/account.md#get-usage) and upgrade before you reach the limit. See [Free plan limits](https://esigncomply.com/docs/guides/test-mode.md#free-plan-limits), [Starter limits](https://esigncomply.com/docs/guides/test-mode.md#starter-limits) and [/pricing.md](https://esigncomply.com/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`.

```json
{
  "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](https://esigncomply.com/docs/guides/certificates.md).

### `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](https://esigncomply.com/docs/api.md).

### `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`.
