Error codes

Errors come back as application/problem+json with a stable code. Match on code, not on the message: codes are never renamed or reused.

{
  "type": "about:blank",
  "title": "this access can't write",
  "status": 403,
  "code": "read_only",
  "detail": "sqlite3: attempt to write a readonly database"
}

Code	HTTP status	Meaning
`bad_request`	400 Bad Request	The request body or a parameter is malformed.
`invalid_name`	400 Bad Request	A name doesn’t match `[a-z0-9][a-z0-9-]{0,62}`.
`empty_statement`	400 Bad Request	The SQL text holds no statement.
`multiple_statements`	400 Bad Request	`query` got more than one statement. Use `batch` for several.
`invalid_params`	400 Bad Request	The parameters don’t match the statement’s placeholders.
`sql_error`	400 Bad Request	SQLite rejected the statement. `detail` has SQLite’s message.
`constraint_violation`	409 Conflict	A UNIQUE, NOT NULL, CHECK or foreign key constraint failed.
`statement_denied`	403 Forbidden	The statement uses something Lumbung doesn’t allow: ATTACH, VACUUM INTO, transaction control, temp objects, a pragma off the allowlist or a denied function.
`read_only`	403 Forbidden	The token can only read, and the statement writes.
`statement_timeout`	408 Request Timeout	The statement ran past the statement timeout and was cancelled. Nothing it wrote was kept.
`value_too_large`	413 Request Entity Too Large	A string, blob or statement is larger than its limit.
`result_too_large`	413 Request Entity Too Large	The result has more rows or bytes than the limit. Nothing partial is returned and writes are rolled back.
`memory_limit`	422 Unprocessable Entity	The statement needed more memory than one connection may use.
`branch_size_limit`	507 Insufficient Storage	The write would grow the branch past its size limit.
`instance_quota_exceeded`	507 Insufficient Storage	The write would grow the instance past its total size quota.
`insufficient_disk`	507 Insufficient Storage	The host disk has less free space than the configured minimum.
`database_not_found`	404 Not Found	No database with that name or id.
`branch_not_found`	404 Not Found	No branch with that name or id in this database.
`name_taken`	409 Conflict	Another database or branch already has that name.
`limit_reached`	409 Conflict	The instance already has the most databases, or the database the most branches, allowed.
`snapshot_not_found`	404 Not Found	No snapshot with that id in this database.
`branch_protected`	409 Conflict	The branch is protected, so it can’t be deleted, reset or overwritten by an import. The default branch is always protected.
`parent_gone`	409 Conflict	The branch can’t be reset because the branch or snapshot it was made from no longer exists.
`branch_not_empty`	409 Conflict	An import into a branch that already has tables needs `mode=replace`.
`invalid_import`	400 Bad Request	The uploaded file isn’t a valid SQLite database or SQL dump, or fails its integrity check.
`import_too_large`	413 Request Entity Too Large	The upload is larger than the import limit or the branch size limit.
`unauthorized`	401 Unauthorized	The `Authorization: Bearer` token is missing, malformed, revoked or expired.
`forbidden`	403 Forbidden	The token is valid but its scope doesn’t allow this.
`rate_limited`	429 Too Many Requests	Too many requests for this token, or too many failed logins from this address. `Retry-After` says when to try again.
`not_found`	404 Not Found	No such endpoint.
`method_not_allowed`	405 Method Not Allowed	The endpoint doesn’t accept this HTTP method.
`invalid_request`	422 Unprocessable Entity	The request doesn’t match the API schema. `errors` lists each problem.
`request_too_large`	413 Request Entity Too Large	The request body is larger than the limit.
`request_timeout`	408 Request Timeout	The request body took too long to arrive.
`idempotency_mismatch`	422 Unprocessable Entity	This `Idempotency-Key` was already used for a different request.
`token_not_found`	404 Not Found	No live token with that id.
`busy`	503 Service Unavailable	The branch stayed locked longer than the busy timeout. Retry.
`unavailable`	503 Service Unavailable	The engine can’t serve: for example meta.db is newer than this binary.
`internal`	500 Internal Server Error	Something failed inside the engine. The log has details.