Errors

When a request fails, the API returns a JSON error envelope with a machine-readable code and a human-readable message.

Error Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Entity not found: Customer"
  }
}

Some errors include a details array with per-field information:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: 2 error(s)",
    "details": [
      { "field": "email", "message": "must be a valid email address" },
      { "field": "name", "message": "name is required" }
    ]
  }
}

Status Codes

Code	Error Code	Description
400	BAD_REQUEST	Invalid request body or parameters
400	FOREIGN_KEY_VIOLATION	Referenced record does not exist
401	UNAUTHORIZED	Missing, invalid, or expired API key
403	FORBIDDEN	API key doesn't have permission for this operation
404	NOT_FOUND	Entity or record not found
409	WORKSPACE_STATUS	Workspace access mode prevents this operation
503	SCHEMA_MIGRATION_IN_PROGRESS	A schema migration is running on the target table
409	UNIQUE_CONSTRAINT_VIOLATION	Duplicate value for a unique column
422	VALIDATION_ERROR	Request data fails constraint validation (includes details)
500	INTERNAL_ERROR	Unexpected server error

Common Errors

Invalid API Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

The key is missing, incorrect, or has been revoked. Check that you're including the full key in the Authorization: Bearer header.

Expired API Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key has expired"
  }
}

Create a new API key in your workspace settings.

Read-Only Key

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This API key has READ_ONLY permissions — data modifications are not allowed"
  }
}

You're using a read-only key for a POST, PUT, or DELETE request. Create a key with Read & Write permissions.

Wrong Workspace

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is not valid for this workspace"
  }
}

The API key belongs to a different workspace than the one in the URL.

Schema Migration in Progress

{
  "error": {
    "code": "SCHEMA_MIGRATION_IN_PROGRESS",
    "message": "Table 'customers' is currently being migrated. Please retry after the migration completes."
  },
  "tableName": "customers",
  "operationId": "abc-123",
  "impactLevel": "BLOCKING",
  "blocksReads": true,
  "blocksWrites": true,
  "retryAfterSeconds": 15,
  "estimatedCompletionAt": "2026-03-17T10:35:00Z"
}

A schema change (column type change, adding constraints, etc.) is running on this table. The response includes a Retry-After header with the number of seconds to wait.

What's blocked depends on the migration:

blocksReads	blocksWrites	Effect
false	true	Reads (GET) still work. Writes (POST/PUT/DELETE) return 503.
true	true	All operations return 503.

Retry your request after the retryAfterSeconds period, or listen for the view.column.schema.changed SSE event to know when the migration completes.

Workspace in Restricted Mode

{
  "error": {
    "code": "WORKSPACE_STATUS",
    "message": "Workspace is in read-only mode"
  }
}

The workspace access mode is preventing write operations. An admin needs to change the workspace back to Active mode.

Entity Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Entity not found: Custoer"
  }
}

The entity name in the URL doesn't match any entity in the workspace. Check for typos — entity names are case-sensitive.

Record Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Record not found: 42"
  }
}

No record exists with the given ID.

Unique Constraint Violation

{
  "error": {
    "code": "UNIQUE_CONSTRAINT_VIOLATION",
    "message": "A record with email '[email protected]' already exists"
  }
}

You're trying to create or update a record with a value that already exists in a unique column. Use a different value or update the existing record instead.

Foreign Key Violation

{
  "error": {
    "code": "FOREIGN_KEY_VIOLATION",
    "message": "Referenced customer_id '999' does not exist in customers"
  }
}

The record references a related record that doesn't exist. Make sure the referenced record exists before creating the relationship.

Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: 2 error(s)",
    "details": [
      { "field": "email", "message": "must be a valid email address" },
      { "field": "age", "message": "must be at least 0" }
    ]
  }
}

The request data doesn't pass the entity's column constraints. Each failed field is listed in the details array. See Validation for the full list of constraint types.