Error Reference

All API errors follow a consistent JSON format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description",
    "resolution": "Suggested fix",
    "docs_url": "https://embedd.to/errors/error_code",
    "request_id": "req_abc123"
  }
}

Error Codes

Authentication Errors

Code	HTTP Status	Description
`unauthorized`	401	Invalid or missing API key / JWT
`key_revoked`	401	API key has been revoked
`permission_denied`	403	`read_only` key attempted a mutating operation

Resolution: Include a valid API key in the Authorization header: Bearer sk_.... For read_only keys, only GET requests and POST /query are allowed.

Organization Errors

Code	HTTP Status	Description
`org_not_found`	404	Organization does not exist
`org_deleting`	403	Organization is being deleted — requests are blocked
`not_a_member`	403	User is not a member of the organization
`insufficient_role`	403	User's role does not have permission for this operation
`owner_cannot_leave`	403	Owner must transfer ownership or delete the org
`cannot_remove_owner`	403	The owner cannot be removed as a member

Invitation Errors

Code	HTTP Status	Description
`already_a_member`	409	Invited email is already a member of the org
`invitation_exists`	409	A pending invitation already exists for this email
`invitation_expired`	410	Invitation token has expired (7-day limit)
`invitation_not_found`	404	Invalid invitation token

Tier Limit Errors

Code	HTTP Status	Description
`tier_limit_reached`	403	Organization has reached a tier limit (tables or vectors)

Resolution: Upgrade your subscription tier or delete unused managed-mode vector tables. Platform mode resources are not subject to tier limits.

Rate Limiting

Code	HTTP Status	Description
`rate_limit_exceeded`	429	Too many requests

Resolution: Check the Retry-After header and wait before retrying. See Rate Limiting.

Not Found Errors

Code	HTTP Status	Description
`environment_not_found`	404	Environment ID does not exist
`connection_not_found`	404	Connection ID does not exist
`embedding_provider_not_found`	404	Embedding provider ID does not exist
`vector_table_not_found`	404	Vector table ID does not exist
`task_not_found`	404	Task ID does not exist
`api_key_not_found`	404	API key ID does not exist

Resolution: Verify the resource ID and ensure it belongs to your organization and environment.

Validation Errors

Code	HTTP Status	Description
`validation_error`	422	Request body failed validation
`connection_not_ready`	422	Connection is not in `connected` status
`vector_table_not_ready`	422	Vector table must be synced before querying

Conflict Errors

Code	HTTP Status	Description
`environment_conflict`	409	Environment has attached resources
`connection_conflict`	409	Connection has attached vector tables
`backfill_in_progress`	409	A backfill is already running
`sync_already_paused`	409	Sync is already paused
`sync_not_paused`	409	Cannot resume — sync is not paused
`org_already_deleting`	409	Organization deletion is already in progress

Permission Errors

Code	HTTP Status	Description
`source_table_access_denied`	403	Cannot read from the source table

Resolution: Grant the required permissions on the source database, then retry.

Error Codes​

Authentication Errors​

Organization Errors​

Invitation Errors​

Tier Limit Errors​

Rate Limiting​

Not Found Errors​

Validation Errors​

Conflict Errors​

Permission Errors​