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)
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.

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
DOCUMENT_TYPE_MISMATCH	400	The flow requires an IBAN_VERIFICATION:v1 or PROOF_OF_ADDRESS:v1 step, but documentImages.documentType does not match
DOCUMENT_TYPE_NOT_VALID	400	documentImages.documentType is IBAN or PROOF_OF_ADDRESS, but the flow does not include a matching unstructured-document step
INCOMPATIBLE_DOCUMENT_TYPE_NODES	400	The flow combines steps that each require a different document type (IBAN, proof of address, identity document)
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

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