# Common Errors

> A troubleshooting matrix for diagnosing API and webhook errors.

A quick reference for the error codes the API can return, with the common cause and the recommended fix.

## General errors

| Code | Description | What to do |
|---|---|---|
| `ALREADY_EXISTS` | The resource you're trying to create already exists. | Check whether the resource was already created. Use an update operation instead of creating a new one. |
| `EXPIRED_CODE` | The provided access code or token has expired. | Generate a new code or request a new link before retrying. |
| `INVALID_BODY` | The request body is malformed. | Check your JSON structure: that it matches the expected schema and no required field is missing. |
| `INVALID_REQUEST` | The request as a whole is invalid. | Check the URL, query parameters, and headers. |
| `RECIPIENT_EXPIRED` | The recipient's signing link has expired. | Generate and resend a new invitation to that recipient. |
| `LIMIT_EXCEEDED` | A usage limit on your plan was exceeded. | Check your [plan limits](/en/resources/rate-limits/) or wait for the next billing cycle. |
| `NOT_FOUND` | The requested resource doesn't exist (404). | Check the resource ID (envelope, document) in the URL, and that it hasn't been deleted. |
| `NOT_IMPLEMENTED` | The requested feature isn't currently available. | Check the documentation for available methods. |
| `NOT_SETUP` | Prior configuration for this action is missing. | Complete the necessary setup in your account before retrying. |
| `INVALID_CAPTCHA` | Captcha validation failed. | Verify the captcha token is generated and sent correctly. |
| `UNAUTHORIZED` | Missing or invalid authentication (401). | Check that your API Key is correct and in the `Authorization` header — see [Authentication](/en/guides/authentication/). |
| `FORBIDDEN` | Access to the resource is denied (403). | Check that your API Key has the permissions needed for that action. |
| `UNKNOWN_ERROR` | Unexpected internal error (500). | Retry later. If it persists, contact support with the payload and the time of the incident. |
| `RETRY_EXCEPTION` | The operation failed temporarily but can be retried. | Implement automatic retries, ideally with exponential backoff. |
| `SCHEMA_FAILED` | Strict schema validation failed. | Check that the data types sent match the OpenAPI spec exactly. |
| `TOO_MANY_REQUESTS` | The rate limit was exceeded (429). | Reduce your call frequency — see [Rate Limits](/en/resources/rate-limits/). |
| `TWO_FACTOR_AUTH_FAILED` | 2FA verification failed. | Check that the 2FA code is correct and hasn't expired. |
| `WEBHOOK_INVALID_REQUEST` | A webhook-related request is invalid. | Check your receiving endpoint's configuration — see [Webhooks](/en/guides/webhooks/). |

## Envelope status errors

These occur when attempting an action that's incompatible with the envelope's current status:

| Code | Description | What to do |
|---|---|---|
| `ENVELOPE_DRAFT` | The action can't be performed because the envelope is still `DRAFT`. | Distribute it first — see [Distribute and the signing experience](/en/guides/integration-guide/#4-distribute-and-the-signing-experience). |
| `ENVELOPE_COMPLETED` | The action can't be performed because the envelope is already `COMPLETED`. | Recipients and fields can't be modified once the signing process is finished. |
| `ENVELOPE_REJECTED` | The action can't be performed because a recipient rejected the envelope. | The signing flow is permanently stopped. Create a new envelope if you need to resend the document. |
| `ENVELOPE_LEGACY` | The envelope uses an obsolete format. | Recreate it with the current API version to interact with it. |

---

## See also

- [Rate Limits](/en/resources/rate-limits/) — rate and plan limits
- [Webhooks](/en/guides/webhooks/) — status change notifications
- [Integration Guide](/en/guides/integration-guide/) — the general flow and its common errors