Error codes
Error response format
All API errors return a consistent JSON structure:
{
"statusCode": 400,
"timestamp": "2026-02-17T09:18:05.040Z",
"path": "/api/v1/...",
"message": "Human-readable error description",
"code": "ERROR_CODE"
}
The code field is only present for domain-specific errors (see Domain-specific error codes below). Generic HTTP errors (e.g. invalid UUID, unauthorized) omit the code field.
HTTP status codes
| Status code | Description |
|---|---|
| 400 Bad Request | Validation failures, invalid request parameters, or invalid client configuration |
| 401 Unauthorized | Missing or invalid OAuth token |
| 403 Forbidden | Accessing resources outside your organization or environment |
| 404 Not Found | Session, flow, flow version, or file not found |
| 409 Conflict | Duplicate resource (e.g. flow already exists) |
| 412 Precondition Failed | Flow cannot execute in its current configuration (missing credentials, template, or step config) |
| 422 Unprocessable Entity | Request semantically valid but failed business validation (e.g. file too large) |
| 500 Internal Server Error | Unexpected server error |
| 503 Service Unavailable | File service temporarily unavailable |
Validation errors
When request body validation fails, the message field follows the pattern:
Validation failed: field.path: error message, another.field: error message
Domain-specific error codes
These codes appear in the code field of the error response.
Migration: renamed error codes
The following error codes were renamed and now return 412 Precondition Failed instead of 400 Bad Request:
| Old code | New code | New HTTP status |
|---|---|---|
SPHINX_CREDENTIALS_NOT_FOUND | DOC_IDV_CREDENTIALS_NOT_FOUND | 412 |
TEMPLATE_ID_NOT_FOUND | TEMPLATE_ID_NOT_IN_SIGNING_SYSTEM | 412 |
TEMPLATE_ID_MISSING_FOR_NODE | TEMPLATE_ID_MISSING_FOR_STEP | 412 |
MISSING_NODE_SHORTNAME | MISSING_SHORTNAME_SIGNING_STEP | 412 |
INCOMPATIBLE_DOCUMENT_TYPE_NODES | INCOMPATIBLE_DOCUMENT_TYPE_STEPS | 412 |
DOCUMENT_TYPE_NOT_VALID | FIELD_VALUE_NOT_ALLOWED | 412 |
DOCUMENT_TYPE_MISMATCH | FIELD_VALUE_NOT_ALLOWED | 412 |
The following error codes were not renamed but now return 412 Precondition Failed instead of 400 Bad Request:
| Code | Old HTTP status | New HTTP status |
|---|---|---|
INVALID_PDF | 400 | 412 |
SIGNATURE_OUT_OF_BOUNDS | 400 | 412 |
If you are parsing error codes or handling HTTP 400 responses, update your integration to use the new code names and expect 412 instead.
Session and flow execution errors
| Code | HTTP status | Description |
|---|---|---|
INVALID_CLIENT | 400 | client_id is missing, not found, or has no allowed redirect URLs configured |
REDIRECT_NOT_ALLOWED | 400 | The provided redirect_url is not in the client's allowlist |
UNAUTHORIZED_ACCESS | 403 | Session environment mismatch or organization ownership violation |
VAULT_ENTRY_NOT_FOUND | 404 | Referenced file does not exist |
VAULT_ENTRY_DELETED | 404 | Referenced file was deleted |
FIELD_VALUE_NOT_ALLOWED | 412 | A field in the request body has a value that is not permitted (e.g. documentImages.documentType is not valid for this flow) |
INCOMPATIBLE_DOCUMENT_TYPE_STEPS | 412 | The flow combines steps that each require a different document type (IBAN, proof of address, identity document) |
TEMPLATE_ID_NOT_IN_SIGNING_SYSTEM | 412 | The provided Template ID does not exist in the signing system |
TEMPLATE_ID_MISSING_FOR_STEP | 412 | None of the flow's requested Template IDs match a signing step account |
DOC_IDV_CREDENTIALS_NOT_FOUND | 412 | DocIDV credentials are not configured for the given shortname and environment |
INVALID_PDF | 412 | An uploaded document could not be parsed as a valid PDF |
SIGNATURE_OUT_OF_BOUNDS | 412 | A signature anchor on a document falls beyond the PDF's last page |
MISSING_SHORTNAME_SIGNING_STEP | 412 | A signing step has no shortname configured for the given environment |
MISSING_STEP_CREDENTIALS | 412 | The flow requires credentials that are not configured for this organisation. |
MISSING_STEP_CONFIG | 412 | One or more steps in the flow require configuration that has not been enabled for this organisation. |
FILE_TOO_LARGE | 422 | An uploaded file exceeds the allowed size limit |
File errors
| Code | HTTP status | Description |
|---|---|---|
ENTRY_NOT_FOUND | 404 | Requested file entry does not exist |
ENTRY_DELETED_ERROR | 404 | Requested file entry has been deleted |
INVALID_FLOW_EXECUTION | 400 | The file request references an invalid flow execution |
PRESIGNED_URL_GENERATION_FAILED | 503 | Failed to generate download URL |
UPLOAD_FAILED | 503 | File upload to storage failed |
ENTRY_IS_NOT_A_BINARY | 503 | Entry is not a binary file |
ENTRY_IS_NOT_A_DATA_BLOCK | 503 | Entry is not a data block |
ENTRY_IS_WRONG_TYPE_OF_DATA_BLOCK | 503 | Entry is a data block but of the wrong type |
ENTRY_ALREADY_ATTACHED | 503 | Entry is already attached to a parent |
The 503 status code for ENTRY_IS_NOT_A_BINARY, ENTRY_IS_NOT_A_DATA_BLOCK, ENTRY_IS_WRONG_TYPE_OF_DATA_BLOCK, and ENTRY_ALREADY_ATTACHED is a fallback mapping — these are client-input or state errors, not transient service unavailability. Do not build retry-on-503 logic for these codes; they represent permanent errors.