> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/error-codes/error-handling-and-api-error-codes.md).

# Error handling and API error codes

This document explains how to interpret API errors and resolve common request failures.

### HTTP status codes

<table><thead><tr><th width="83">Code</th><th width="186">Meaning</th><th>What to check first</th></tr></thead><tbody><tr><td><code>400</code></td><td>Bad request</td><td>Request format, required values, JSON, XML, and query parameters</td></tr><tr><td><code>401</code></td><td>Unauthorized</td><td>Token and <code>Authorization</code> header</td></tr><tr><td><code>402</code></td><td>Payment Required</td><td>Billing limits, plan restrictions, and enabled functionality</td></tr><tr><td><code>403</code></td><td>Forbidden</td><td>Permissions and access to the mailbox, account, or object</td></tr><tr><td><code>404</code></td><td>Not found</td><td>UUID, environment, and object availability</td></tr><tr><td><code>409</code></td><td>Conflict</td><td>Current entity state and duplicate operations</td></tr><tr><td><code>410</code></td><td>Entity gone</td><td>Whether the entity was deleted, archived, or became unavailable</td></tr><tr><td><code>422</code></td><td>Unprocessable entity</td><td>Template values, XML, fields, and validation rules</td></tr><tr><td><code>425</code></td><td>Too early</td><td>Whether the previous operation is complete</td></tr><tr><td><code>429</code></td><td>Too many requests</td><td>Endpoint rate limits and request frequency</td></tr></tbody></table>

### Authentication and access errors

Use `401` when the request is not authenticated. Check the token and header format.

```http
Authorization: Bearer {token}
```

Use `403` when the request is authenticated but lacks access. Check the token owner, mailbox context, and permissions.

{% columns %}
{% column %}

* token belongs to the expected user or integration
* correct environment
* access to the target mailbox
* correct `mailboxUuid` header
  {% endcolumn %}

{% column %}

* access to the template or envelope
* access to the account or dictionary
* permission for the requested action
  {% endcolumn %}
  {% endcolumns %}

### Request format and validation errors

Use `400` when the request format is invalid. Use `422` when the request format is valid but values cannot be processed.

For `400`, check:

{% columns %}
{% column %}

* endpoint URL and HTTP method
* required headers
* `Content-Type`
* path and query parameters
  {% endcolumn %}

{% column %}

* URL-encoded query values
* valid JSON body
* valid XML in `data`
* endpoint request format
  {% endcolumn %}
  {% endcolumns %}

For `422`, check:

{% columns %}
{% column %}

* matching `templateUuid` and `templateVersion`
* role and document IDs from the template version
* field names in the selected document
* required field values
  {% endcolumn %}

{% column %}

* field formats and validation rules
* dynamic table group names and indexes
* attachment UUIDs
* active mailbox role and envelope state
  {% endcolumn %}
  {% endcolumns %}

### Mailbox and file errors

Use mailbox UUIDs only in their intended context. Do not interchange sender, recipient, and current mailbox values.

```http
GET /api/v1/mailbox/{mailboxUuid}?UUID={envelopeUuid}
Authorization: Bearer {token}
Content-Type: application/json
mailboxUuid: {mailboxUuid}
```

Upload a file before referencing it in an envelope. Use the returned `attachmentId` as `attachmentUuid`.

```xml
<field name="supporting_file" attachmentUuid="{attachmentId}">
  {filename}
</field>
```

### Retry behavior

Retry only when the endpoint contract and request state allow it.

| Response                                        | Action                                           |
| ----------------------------------------------- | ------------------------------------------------ |
| `425`                                           | Wait before retrying                             |
| `429`                                           | Reduce request frequency and retry after a delay |
| `409`                                           | Check the current entity state before retrying   |
| `400`, `401`, `402`, `403`, `404`, `410`, `422` | Correct the underlying issue before retrying     |

{% hint style="warning" %}
Do not retry data-creating requests until you confirm their current state.
{% endhint %}

### Safe error logging

Log only data needed to diagnose the issue. Mask secrets before storing or sharing logs.

{% columns %}
{% column %}
**Safe to log**

* endpoint name
* HTTP method
* status code
* environment
* sanitized error message
  {% endcolumn %}

{% column %}
**Do not log**

* API tokens
* passwords
* private keys
* full `Authorization` headers
* document and file contents
  {% endcolumn %}
  {% endcolumns %}

```http
Authorization: Bearer ***
```

### Application error codes

Error codes identify the affected product area. Use the error detail and response context to locate the failed value or operation.

#### Common

<table><thead><tr><th width="85">Code</th><th>Error detail</th><th>Resolution</th></tr></thead><tbody><tr><td><code>1000</code></td><td>Undefined exception</td><td>Record the sanitized error details and contact support</td></tr><tr><td><code>1001</code></td><td>Record not found</td><td>Check the request parameter and object UUID</td></tr><tr><td><code>1004</code></td><td>Empty value for required field</td><td>Provide a value for the required field</td></tr><tr><td><code>1005</code></td><td>Too many requests</td><td>Wait before retrying the request</td></tr><tr><td><code>1006</code></td><td>Validation failed</td><td>Use the response details to identify the failed field and rule</td></tr><tr><td><code>1008</code></td><td>Invalid XML</td><td>Correct the XML structure</td></tr><tr><td><code>1019</code></td><td>File is not ready for download</td><td>Wait and retry the download</td></tr><tr><td><code>1022</code></td><td>Request header required</td><td>Add the required header</td></tr><tr><td><code>1023</code></td><td>Request query parameter required</td><td>Add the required query parameter</td></tr><tr><td><code>1024</code></td><td>Request body parameter required</td><td>Add the required request body parameter</td></tr><tr><td><code>1025</code></td><td>Request path parameter required</td><td>Add the required path parameter</td></tr><tr><td><code>1027</code></td><td>Authentication token has expired or was revoked</td><td>Authorize again</td></tr><tr><td><code>1032</code></td><td>Attachment not found</td><td>Check the attachment UUID</td></tr><tr><td><code>1039</code></td><td>Attachment belongs to another mailbox</td><td>Use an attachment available in the current mailbox context</td></tr><tr><td><code>1055</code></td><td>Payload is too large</td><td>Reduce the request or file size</td></tr></tbody></table>

#### Template and envelope

<table><thead><tr><th width="84">Code</th><th>Error detail</th><th>Resolution</th></tr></thead><tbody><tr><td><code>40001</code></td><td>Document not found</td><td>Check the document ID</td></tr><tr><td><code>40002</code></td><td>Template is archived</td><td>Use an active template</td></tr><tr><td><code>40003</code></td><td>Template not found</td><td>Check the template UUID</td></tr><tr><td><code>40051</code></td><td>Template UUID and version mismatch</td><td>Use values from the same template structure</td></tr><tr><td><code>40052</code></td><td>Template role not found</td><td>Check the role ID</td></tr><tr><td><code>50001</code></td><td>Envelope field is empty</td><td>Provide a value for the required field</td></tr><tr><td><code>50007</code></td><td>Role mailbox UUID is invalid</td><td>Assign a valid mailbox UUID to each required role</td></tr><tr><td><code>50008</code></td><td>Role ID is invalid</td><td>Use role IDs from the selected template version</td></tr><tr><td><code>50011</code></td><td>Envelope not found</td><td>Check the envelope UUID and mailbox context</td></tr><tr><td><code>50012</code></td><td>Template UUID or version is required</td><td>Provide both template identifiers</td></tr><tr><td><code>50017</code></td><td>Envelope document not found in XML</td><td>Use the document ID from the template structure</td></tr><tr><td><code>50033</code></td><td>No XML data for envelope</td><td>Provide the envelope XML in the request</td></tr><tr><td><code>50049</code></td><td>No active role for mailbox</td><td>Wait for the active role or use the correct mailbox</td></tr><tr><td><code>50050</code></td><td>Wrong envelope status</td><td>Check the envelope state before sending the request</td></tr><tr><td><code>50067</code></td><td>Attachment UUID is required</td><td>Use the uploaded attachment ID as `attachmentUuid`</td></tr><tr><td><code>50079</code></td><td>Roles do not match template roles</td><td>Update the envelope XML flow</td></tr></tbody></table>

#### Access and object errors

<table><thead><tr><th width="130">Area</th><th width="86">Code</th><th>Error detail</th><th>Resolution</th></tr></thead><tbody><tr><td>User</td><td><code>10001</code></td><td>User not found</td><td>Check the user UUID</td></tr><tr><td>Account</td><td><code>20001</code></td><td>Account not found</td><td>Check the account UUID</td></tr><tr><td>Mailbox</td><td><code>30001</code></td><td>Mailbox not found</td><td>Check the mailbox UUID</td></tr><tr><td>Dictionary</td><td><code>60001</code></td><td>Dictionary not found</td><td>Check the dictionary UUID</td></tr><tr><td>Integration</td><td><code>80002</code></td><td>Integration rule not found</td><td>Check the integration rule UUID</td></tr><tr><td>Permissions</td><td><code>90002</code></td><td>Insufficient account privileges</td><td>Request the required account permission</td></tr><tr><td>Permissions</td><td><code>90003</code></td><td>Insufficient mailbox privileges</td><td>Request the required mailbox permission</td></tr><tr><td>Permissions</td><td><code>90009</code></td><td>No access to template</td><td>Request access to the template</td></tr><tr><td>Permissions</td><td><code>90013</code></td><td>No access to mailbox</td><td>Request access to the mailbox</td></tr><tr><td>Permissions</td><td><code>90015</code></td><td>No access to envelope</td><td>Use a mailbox included in the envelope flow</td></tr><tr><td>Billing</td><td><code>120003</code></td><td>Plan limit reached</td><td>Adjust usage or change the billing plan</td></tr></tbody></table>

### Related topics

{% columns %}
{% column %}

* [Authentication and application tokens](/introduction/authentication-and-application-tokens.md)
* [API token security](/introduction/api-token-security.md)
* [Working with XML payloads](/guides/xml-payloads.md)
  {% endcolumn %}

{% column %}

* [Working with templates and reusable IDs](/guides/templates-and-reusable-ids.md)
* [Working with envelope fields](/guides/envelope-fields.md)
* [Uploading files and external documents](/guides/files-and-external-documents.md)
  {% endcolumn %}
  {% endcolumns %}