Guides/Errors

Errors

The shape of every error response and the Data API error codes.

Every error response from the Data API has the same envelope:

{ "error": { "code": "record.notFound", "message": "Record not found", "details": {} } }

details is optional.

Status codes

Status	Code	Meaning
`401`	`auth.invalid`	Missing, malformed, unknown, expired, or revoked Bearer token.
`403`	`database.disabled`	Workspace Database flag is off.
`403`	`scope.denied`	Valid key, missing `tables:read` or `tables:write`.
`404`	`table.notFound`	Table UUID is not in this workspace.
`404`	`record.notFound`	Record does not exist on that table.
`404`	`column.notFound`	Column missing, or FILE route used on a non-FILE column.
`400`	`filter.unsupported`	List filter cannot be applied honestly (computed / FILE / REFERENCE / MULTISELECT / LONGTEXT).
`413`	`storage.limitReached`	Workspace storage headroom would be exceeded.
`422`	`fields.unknown`	Payload key is not a column name.
`422`	`fields.invalid`	Value failed validation (or invalid JSON / cursor).
`422`	`fields.required`	Required write column missing on create.
`422`	`file.use_upload`	FILE JSON on POST/PATCH — use presign → PUT → register.
`422`	`file.mimeNotAllowed`	MIME type not allowed on that FILE column.
`422`	`file.tooLarge`	File larger than the column max.
`422`	`file.tooMany`	Cell would exceed the FILE count cap.
`422`	`file.malformed`	Register key is empty, contains `..`, or is outside `{tableId}/{recordId}/`.
`422`	`datetime.invalid`	DATETIME was not an ISO-8601 string.
`422`	`bulk.tooMany`	Bulk create exceeded 50 rows.
`422`	`reference.unsupported`	REFERENCE write used a non-record entity type.
`429`	`rate.limited`	Per-key RPM bucket empty. See Rate limits.

When validation fails, details may name the column:

{
  "error": {
    "code": "fields.unknown",
    "message": "Unknown field",
    "details": { "key": "NotAColumn" }
  }
}