Errors

Every error is returned as a JSON body with a fixed shape:

{ "status": "error", "message": "The user record was not found" }

Successful responses always include "status": "ok". As a defensive pattern, check the JSON status field in addition to the HTTP status code.

HTTP status codes

Code	Meaning
400	Bad request — malformed body, missing or invalid parameters, schema validation failure
403	Access denied — missing/invalid API token, insufficient permissions, disabled feature, or license limit
404	The referenced record was not found
409	Conflict — duplicate record, name already in use, or operation conflicts with the record’s current state
500	Internal server error

Databunker Pro releases prior to the 2026-07 update returned HTTP 405 for most error conditions. If you run an older release, treat any non-2xx response as an error and rely on the JSON status/message fields.

Common error messages

The message field is human-readable. Representative messages per status code:

400 — Bad request

Message	Cause
`Missing API request parameters: profile`	A required request field was omitted (lists the fields)
`Failed to decode the request body`	The body is not valid JSON
`Bad UUID`	An identifier is not a valid UUID
`The mode parameter has an incorrect format`	An enum-style parameter has an unexpected value
`Failed to validate user schema: ...`	The profile fails the configured user record schema
`The filedata parameter is not valid base64`	File upload payload is not base64-encoded

403 — Access denied

Message	Cause
`Access denied`	Missing/invalid `X-Bunker-Token`, or the token’s policy denies the operation
`API access denied`	Policy evaluation rejected the request
`Record limit reached`	The license record cap was hit — new records cannot be created, while reads, updates and deletes keep working
`License expired`	The installation license has expired and the vault is read-only — reads, exports and deletions still work
`BulkListUsers is disabled`	The `list_users` configuration flag is off
`The unlockuuid value was not found or is not valid`	The bulk-unlock UUID is missing, wrong, or past its 60-second lifetime
`Only the main tenant admin can ...`	A main-tenant-only endpoint was called with a sub-tenant token

404 — Not found

Message	Cause
`The user record was not found`	No user matches the given `mode`/`identity`
`Token not found`	The token UUID does not exist or has expired
`The group record was not found`	Unknown group ID
`The legal basis record was not found`	Unknown legal-basis `brief`
`The API request was not found`	The `/v2/<name>` endpoint name does not exist

409 — Conflict

Message	Cause
`Duplicate index: email`	Another user already holds this unique index value (email/phone/login/custom)
`The role record already exists`	Create called with a name that is already taken
`Duplicate tenant name`	Tenant name already in use
`This user request is closed`	Approve/cancel called on a request that is no longer open

500 — Internal server error

Message	Cause
`Internal error` / `Database error`	Unexpected server-side failure — check the server logs
`Failed to decrypt the user record`	Storage-level failure (e.g. key mismatch) — check the server logs

Server-side error details (database errors, stack context) are never included in API responses — they are written to the server log and the audit trail only.

Special cases

UserPrelogin captcha failure returns HTTP 200 with {"status":"error","message":"captcha-error"} — the user portal login flow consumes this in-body. Always check the status field on prelogin responses.
Public endpoints (UserPrelogin, UserLogin, CaptchaCreate, SharedRecordGet, TenantGetUIConf) require no token; all other endpoints return 403 without a valid one — see Authentication.
Unknown endpoint names under /v2/ return 404 with The API request was not found; unknown URL paths outside /v2/ return 404 with endpoint is missing.

API Basics

User Tokenization

File Storage

Bulk Operations

App Data Management

Legal Basis Management

Agreement Management

Processing Activity Management

Format Preserving Tokenization

Group Management

Role Management

Policy Management

Authentication

Audit Management

Tenant Management

Shared Records

Session Management

System Operations

HTTP status codes

Common error messages

400 — Bad request

403 — Access denied

404 — Not found

409 — Conflict

500 — Internal server error

Special cases

​HTTP status codes

​Common error messages

​400 — Bad request

​403 — Access denied

​404 — Not found

​409 — Conflict

​500 — Internal server error

​Special cases

HTTP status codes

Common error messages

400 — Bad request

403 — Access denied

404 — Not found

409 — Conflict

500 — Internal server error

Special cases