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

Resolution: Include a valid API key in the Authorization header: Bearer sk_...

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

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

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.