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
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.

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.