Responses and errors

Every tool returns a single text content block that contains JSON. Successful calls wrap the result in data. Failed calls set isError: true and wrap the failure in error.

{
  "content": [
    { "type": "text", "text": "{\"data\":{\"updated\":2}}" }
  ]
}

{
  "content": [
    { "type": "text", "text": "{\"error\":{\"code\":\"VALIDATION\",\"message\":\"Table \\\"book\\\" does not exist\"}}" }
  ],
  "isError": true
}

The rest of this reference shows the decoded JSON inside text.

Error codes

Code	Meaning	What to do
`ACCESS_DENIED`	The project doesn’t exist, you can’t access it, you need write access, or the connection is read-only	Check the project id with `list_projects` and your `permission`
`VALIDATION`	The input is invalid: an unknown table or column, a bad name, a value that doesn’t fit its type, a missing filter	Fix the input. The message says what’s wrong.
`QUOTA_EXCEEDED`	A limit was reached: projects, tables, columns, or storage	Free space or capacity, then retry
`CONFLICT`	The table, column, value, or invitation already exists	Use the existing one, or pick another name
`RATE_LIMITED`	The per-minute call or write budget ran out	Wait a minute and retry
`INTERNAL`	An unexpected server error. The message is always `Request failed`.	Retry. If it persists, contact [email protected].

Error messages are written to be shown to people and are safe to act on. They name your own tables and columns, never internal identifiers.

Common messages

Access

Message	Cause
`Access denied`	Missing or forbidden project, or a workspace role that doesn’t allow the action
`This connection was approved read-only; reconnect and grant write access to make changes`	A write tool was called with a `mcp:read` token

Validation

Message	Cause
`Table "books" does not exist`	Unknown table name
`Table "books" has no column "isbn"`	Unknown column in a row, filter, or sort
`Column "rating" expects a integer value`	The value doesn’t fit the column type
`Column "title" is required`	A `NOT NULL` column got no value, or a `NOT NULL` column was added to a table that has rows
`Invalid table name "Books": use lowercase letters, digits and underscores, starting with a letter or underscore (max 63 characters)`	Name doesn’t match the naming rules
`update requires at least one filter`	`update_rows` or `delete_rows` without filters
`At most 100 rows per insert`	Too many rows in one `insert_rows` call
`Value for column "notes" exceeds 16384 bytes`	One value is over 16 KB
`A row may hold at most 64 KB of data`	A whole row is over 64 KB
`Referenced row does not exist, or the row is still referenced by another table`	A foreign key value points at a missing row, or a delete hit a `restrict` foreign key
`Query took too long; narrow it with filters or a smaller limit`	The query hit the 5-second statement timeout

Quotas

Message	Cause
`This workspace has reached its limit of 10 projects`	Project quota
`This project has reached its limit of 25 tables`	Table quota
`A table can have at most 50 columns`	Column quota
`Project storage limit (50 MB) reached; delete rows or tables to free space`	Storage quota

Rate limits

Message	Cause
`Too many requests; wait a minute and retry`	More than 300 calls in a minute
`Write budget exhausted (60 per minute); wait a minute and retry`	More than 60 writes in a minute

Value formats in results

Rows come back as JSON objects keyed by column name:

Type	Returned as
`text`, `uuid`	String
`integer`	Number
`numeric`	String, to preserve precision, such as `"1499.99"`
`boolean`	`true` or `false`
`timestamptz`	ISO 8601 string in UTC, such as `"2026-11-03T09:00:00.000Z"`
`jsonb`	The JSON value
`NULL`	`null`

Overview

Read tools

Write tools

Destructive tools

Responses and errors

Error codes

Common messages

Access

Validation

Quotas

Rate limits

Value formats in results

​Error codes

​Common messages

​Access

​Validation

​Quotas

​Rate limits

​Value formats in results

Error codes

Common messages

Access

Validation

Quotas

Rate limits

Value formats in results