Error handling and API error codes

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

HTTP status codes

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

Authentication and access errors

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

Authorization: Bearer {token}

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

• token belongs to the expected user or integration

• correct environment

• access to the target mailbox

• correct mailboxUuid header

• access to the template or envelope

• access to the account or dictionary

• permission for the requested action

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:

• endpoint URL and HTTP method

• required headers

• Content-Type

• path and query parameters

• URL-encoded query values

• valid JSON body

• valid XML in data

• endpoint request format

For 422, check:

• matching templateUuid and templateVersion

• role and document IDs from the template version

• field names in the selected document

• required field values

• field formats and validation rules

• dynamic table group names and indexes

• attachment UUIDs

• active mailbox role and envelope state

Mailbox and file errors

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

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.

<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

Do not retry data-creating requests until you confirm their current state.

Safe error logging

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

Safe to log

• endpoint name

• HTTP method

• status code

• environment

• sanitized error message

Do not log

• API tokens

• passwords

• private keys

• full Authorization headers

• document and file contents

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

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

Template and envelope

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

Access and object errors

Area	Code	Error detail	Resolution
User	10001	User not found	Check the user UUID
Account	20001	Account not found	Check the account UUID
Mailbox	30001	Mailbox not found	Check the mailbox UUID
Dictionary	60001	Dictionary not found	Check the dictionary UUID
Integration	80002	Integration rule not found	Check the integration rule UUID
Permissions	90002	Insufficient account privileges	Request the required account permission
Permissions	90003	Insufficient mailbox privileges	Request the required mailbox permission
Permissions	90009	No access to template	Request access to the template
Permissions	90013	No access to mailbox	Request access to the mailbox
Permissions	90015	No access to envelope	Use a mailbox included in the envelope flow
Billing	120003	Plan limit reached	Adjust usage or change the billing plan

Related topics

• Authentication and application tokens

• API token security

• Working with XML payloads

• Working with templates and reusable IDs

• Working with envelope fields

• Uploading files and external documents