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