Error Codes Reference

Overview

This page provides a comprehensive reference for all error codes you may encounter when using the dialektai API.

HTTP Status Codes

2xx Success

200 OK

Description: Request succeeded

Example Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "My Database",
    "connection_type": "postgresql",
    "created_at": "2025-10-18T10:00:00Z"
  }
}

201 Created

Description: Resource successfully created

Example Response:

{
  "success": true,
  "data": {
    "id": 12345,
    "name": "New Database",
    "created_at": "2025-10-18T10:00:00Z"
  },
  "message": "Database created successfully"
}

4xx Client Errors

400 Bad Request

Description: Invalid request format or parameters

Common Causes:

Example Error:

{
  "error": true,
  "message": "Request validation failed",
  "error_code": "VALIDATION_ERROR",
  "status_code": 400,
  "details": [
    {
      "field": "body.database_id",
      "message": "Field required",
      "code": "VALIDATION_ERROR"
    }
  ],
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

401 Unauthorized

Description: Missing or invalid authentication credentials

Common Causes:

Example Error:

{
  "error": true,
  "message": "Invalid authentication credentials",
  "error_code": "AUTH_INVALID_CREDENTIALS",
  "status_code": 401,
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

# ✅ Correct format for API keys
curl -H "X-API-Key: your_api_key_here"

# ❌ Wrong formats
curl -H "Authorization: Bearer your_api_key_here"  # Wrong: Use X-API-Key for API keys
curl -H "Authorization: your_api_key_here"         # Wrong: Missing header name
curl -H "API-Key: your_api_key_here"               # Wrong: Use X-API-Key prefix

# Note: Authorization: Bearer is only for JWT tokens from web portal login

403 Forbidden

Description: Valid credentials but insufficient permissions

Common Causes:

Example Error:

{
  "error": true,
  "message": "Invalid X-Tenant-Id header format. Must be a positive integer.",
  "error_code": "AUTH_INSUFFICIENT_PERMISSIONS",
  "status_code": 403,
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

404 Not Found

Description: Resource does not exist

Common Causes:

Example Error:

{
  "error": true,
  "message": "Database connection not found",
  "error_code": "NOT_FOUND_DATABASE",
  "status_code": 404,
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

422 Unprocessable Entity

Description: Request is valid but cannot be processed

Common Causes:

Example Error:

{
  "error": true,
  "message": "Request validation failed",
  "error_code": "VALIDATION_ERROR",
  "status_code": 422,
  "details": [
    {
      "field": "connection_config",
      "message": "Cannot connect to database: Connection refused",
      "code": "CONNECTION_FAILED"
    }
  ],
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

429 Too Many Requests

Description: Rate limit exceeded

Common Causes:

Example Error:

{
  "error": true,
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "error_code": "QUOTA_RATE_LIMIT_EXCEEDED",
  "status_code": 429,
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Response Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1697624400

Resolution:

Example Retry Logic (Python):

import time
import requests

def make_request_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Max retries exceeded")

5xx Server Errors

500 Internal Server Error

Description: Unexpected server error

Common Causes:

Example Error:

{
  "error": true,
  "message": "An unexpected error occurred",
  "error_code": "SYSTEM_INTERNAL_ERROR",
  "status_code": 500,
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

503 Service Unavailable

Description: Service temporarily unavailable

Common Causes:

Example Error:

{
  "error": true,
  "message": "Service temporarily unavailable. Please try again later.",
  "error_code": "SYSTEM_SERVICE_UNAVAILABLE",
  "status_code": 503,
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Response Headers:

Retry-After: 300

Resolution:

Domain-Specific Errors

Database Connection Errors

DB_CONNECTION_FAILED

Description: Failed to connect to customer database

Error Code: DB_CONNECTION_FAILED

HTTP Status: 500

Example Error:

{
  "error": true,
  "message": "Failed to connect to database",
  "error_code": "DB_CONNECTION_FAILED",
  "status_code": 500,
  "details": [
    {
      "field": "database_id",
      "message": "Connection timeout after 30 seconds",
      "code": "CONNECTION_TIMEOUT"
    }
  ],
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

DB_QUERY_FAILED

Description: Database query execution failed

Error Code: DB_QUERY_FAILED

HTTP Status: 500

Example Error:

{
  "error": true,
  "message": "Query execution failed",
  "error_code": "DB_QUERY_FAILED",
  "status_code": 500,
  "details": [
    {
      "field": "query",
      "message": "Query timeout after 30 seconds",
      "code": "QUERY_TIMEOUT"
    }
  ],
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

DB_SCHEMA_ERROR

Description: Database schema introspection or validation error

Error Code: DB_SCHEMA_ERROR

HTTP Status: 500

Example Error:

{
  "error": true,
  "message": "Failed to introspect database schema",
  "error_code": "DB_SCHEMA_ERROR",
  "status_code": 500,
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

Schema Indexing Errors

INDEXING_QUOTA_EXCEEDED

Description: Schema indexing quota exceeded for current billing period

Error Code: INDEXING_QUOTA_EXCEEDED

HTTP Status: 429

Example Error:

{
  "error": true,
  "message": "Schema indexing quota exceeded for this billing period",
  "error_code": "INDEXING_QUOTA_EXCEEDED",
  "status_code": 429,
  "details": [
    {
      "field": "quota",
      "message": "Used 10 of 10 allowed schema indexing operations",
      "code": "QUOTA_EXCEEDED"
    }
  ],
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

LLM Provider Errors

EXTERNAL_LLM_ERROR

Description: LLM provider API returned an error

Error Code: EXTERNAL_LLM_ERROR

HTTP Status: 500

Example Error:

{
  "error": true,
  "message": "LLM provider API error: Invalid API key",
  "error_code": "EXTERNAL_LLM_ERROR",
  "status_code": 500,
  "details": [
    {
      "field": "provider",
      "message": "OpenAI API authentication failed",
      "code": "AUTH_FAILED"
    }
  ],
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

QUOTA_MONTHLY_LIMIT_EXCEEDED

Description: Monthly API quota exceeded

Error Code: QUOTA_MONTHLY_LIMIT_EXCEEDED

HTTP Status: 429

Example Error:

{
  "error": true,
  "message": "Monthly API quota exceeded",
  "error_code": "QUOTA_MONTHLY_LIMIT_EXCEEDED",
  "status_code": 429,
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

QUOTA_RATE_LIMIT_EXCEEDED

Description: Rate limit exceeded (too many requests)

Error Code: QUOTA_RATE_LIMIT_EXCEEDED

HTTP Status: 429

Example Error:

{
  "error": true,
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "error_code": "QUOTA_RATE_LIMIT_EXCEEDED",
  "status_code": 429,
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

Tenant Filtering Errors

INVALID_TENANT_ID

Description: Invalid X-Tenant-Id header format

Error Code: AUTH_INSUFFICIENT_PERMISSIONS

HTTP Status: 403

Example Error:

{
  "error": true,
  "message": "Invalid X-Tenant-Id header format. Must be a positive integer.",
  "error_code": "AUTH_INSUFFICIENT_PERMISSIONS",
  "status_code": 403,
  "details": [
    {
      "field": "X-Tenant-Id",
      "message": "Received: 'invalid-id'",
      "code": "INVALID_FORMAT"
    }
  ],
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

// ❌ Wrong
tenantId: "user-123"

// ✅ Correct
tenantId: 123

TENANT_ID_REQUIRED

Description: X-Tenant-Id header required but not provided

Error Code: AUTH_INSUFFICIENT_PERMISSIONS

HTTP Status: 403

Example Error:

{
  "error": true,
  "message": "X-Tenant-Id header is required when organization scoping is enabled for this database.",
  "error_code": "AUTH_INSUFFICIENT_PERMISSIONS",
  "status_code": 403,
  "details": [
    {
      "field": "X-Tenant-Id",
      "message": "Database requires tenant filtering but header not provided",
      "code": "MISSING_REQUIRED_HEADER"
    }
  ],
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Resolution:

Success Response Formats

All successful API responses use one of three standardized wrapper formats:

DataResponse[T] - Single Entity Response

Used for GET (single), POST, PUT, PATCH operations returning data.

{
  "success": true,
  "data": {
    "id": 1,
    "name": "My Database",
    "created_at": "2025-10-18T10:00:00Z"
  },
  "message": "Database created successfully"
}

Fields:

SuccessResponse - Operation Status

Used for DELETE and UPDATE operations that return status only (no data).

{
  "success": true,
  "message": "Database connection deleted successfully"
}

Fields:

PaginatedResponse[T] - List with Pagination

Used for GET (list) operations with pagination support.

{
  "success": true,
  "data": [
    {"id": 1, "name": "Item 1"},
    {"id": 2, "name": "Item 2"}
  ],
  "pagination": {
    "current_page": 1,
    "page_size": 20,
    "total_items": 150,
    "total_pages": 8,
    "has_next": true,
    "has_previous": false
  }
}

Fields:

Error Response Format

All error responses follow this standard format:

{
  "error": true,
  "message": "Human-readable error message",
  "error_code": "VALIDATION_ERROR",
  "status_code": 400,
  "details": [
    {
      "field": "email",
      "message": "Invalid email format",
      "code": "INVALID_EMAIL"
    }
  ],
  "trace_id": "req-12345",
  "timestamp": "2025-10-18T10:30:00Z"
}

Field Descriptions:

Rate Limits

Current Rate Limits

Plan Requests/Minute Requests/Hour Concurrent Requests
Free 10 100 2
Starter 100 5,000 10
Professional 500 25,000 50
Enterprise Custom Custom Custom

Rate Limit Headers

All API responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1697624400

Example Check:

response = requests.post(url, headers=headers)

limit = int(response.headers.get('X-RateLimit-Limit'))
remaining = int(response.headers.get('X-RateLimit-Remaining'))
reset = int(response.headers.get('X-RateLimit-Reset'))

print(f"Rate limit: {remaining}/{limit}")
print(f"Resets at: {datetime.fromtimestamp(reset)}")

Complete Error Code Reference

All error codes used in the API, grouped by category:

Authentication & Authorization (AUTH_*)

Error Code HTTP Status Description
AUTH_INVALID_CREDENTIALS 401 Invalid username/password or API key
AUTH_TOKEN_EXPIRED 401 JWT token has expired
AUTH_TOKEN_INVALID 401 JWT token is malformed or invalid
AUTH_INSUFFICIENT_PERMISSIONS 403 User lacks required permissions
AUTH_ACCOUNT_SUSPENDED 403 User account has been suspended
AUTH_ORGANIZATION_INACTIVE 403 Organization is inactive or suspended
AUTH_EMAIL_NOT_VERIFIED 401 Email address not verified
AUTH_2FA_REQUIRED 401 Two-factor authentication required
AUTH_2FA_INVALID_CODE 401 Invalid 2FA code provided

Resource Not Found (NOT_FOUND_*)

Error Code HTTP Status Description
NOT_FOUND_RESOURCE 404 Generic resource not found (route, endpoint, or unknown resource)
NOT_FOUND_DATABASE 404 Database connection not found
NOT_FOUND_ORGANIZATION 404 Organization not found
NOT_FOUND_USER 404 User not found
NOT_FOUND_API_KEY 404 API key not found
NOT_FOUND_JOB 404 Background job not found
NOT_FOUND_PERSONALITY 404 AI personality not found
NOT_FOUND_PATTERN 404 Query pattern not found
NOT_FOUND_SESSION 404 Chat session not found

Validation Errors (VALIDATION_*)

Error Code HTTP Status Description
VALIDATION_ERROR 400 General validation error
VALIDATION_INVALID_EMAIL 400 Invalid email format
VALIDATION_INVALID_PASSWORD 400 Password doesn't meet requirements
VALIDATION_MISSING_REQUIRED_FIELD 400 Required field is missing
VALIDATION_INVALID_FORMAT 400 Invalid data format

Business Logic Errors (BUSINESS_*)

Error Code HTTP Status Description
BUSINESS_DUPLICATE_ENTRY 400 Duplicate entry (e.g., email already exists)
BUSINESS_OPERATION_FAILED 400 Business operation failed
BUSINESS_INVALID_STATE 400 Invalid state for operation
BUSINESS_QUOTA_EXCEEDED 429 Quota or limit exceeded
BUSINESS_LIMIT_EXCEEDED 429 Resource limit exceeded
BUSINESS_SUBSCRIPTION_REQUIRED 403 Operation requires active subscription
BUSINESS_FEATURE_NOT_AVAILABLE 403 Feature not available in current plan

Quota & Subscription Errors (QUOTA_*, SUBSCRIPTION_*)

Error Code HTTP Status Description
QUOTA_MONTHLY_LIMIT_EXCEEDED 429 Monthly API quota exceeded
QUOTA_RATE_LIMIT_EXCEEDED 429 Rate limit exceeded (too many requests)
SUBSCRIPTION_CANCELED 403 Subscription has been canceled
SUBSCRIPTION_PAST_DUE 403 Subscription payment past due
INDEXING_QUOTA_EXCEEDED 429 Schema indexing quota exceeded

Database Errors (DB_*)

Error Code HTTP Status Description
DB_CONNECTION_FAILED 500 Failed to connect to customer database
DB_QUERY_FAILED 500 Database query execution failed
DB_TRANSACTION_FAILED 500 Database transaction failed
DB_SCHEMA_ERROR 500 Schema introspection or validation error

External Service Errors (EXTERNAL_*)

Error Code HTTP Status Description
EXTERNAL_STRIPE_ERROR 500 Stripe payment processing error
EXTERNAL_LLM_ERROR 500 LLM provider API error
EXTERNAL_SERVICE_UNAVAILABLE 503 External service unavailable

System Errors (SYSTEM_*)

Error Code HTTP Status Description
SYSTEM_INTERNAL_ERROR 500 Internal server error
SYSTEM_SERVICE_UNAVAILABLE 503 Service temporarily unavailable
SYSTEM_RATE_LIMIT_EXCEEDED 429 System rate limit exceeded
SYSTEM_CONFIGURATION_ERROR 500 System configuration error

SSO Errors (SSO_*)

Error Code HTTP Status Description
SSO_NOT_CONFIGURED 400 SSO not configured for organization
SSO_NOT_ENABLED 403 SSO not enabled for organization
SSO_CONFIGURATION_ERROR 500 SSO configuration error
SSO_INVALID_TOKEN 401 Invalid SSO token
SSO_TOKEN_EXPIRED 401 SSO token expired
SSO_MISSING_CLAIMS 400 Required SSO claims missing
SSO_DOMAIN_NOT_ALLOWED 403 Email domain not allowed for SSO
SSO_USER_NOT_PROVISIONED 404 SSO user not provisioned

Custom Exception Types

The API uses custom exception classes that automatically generate standardized error responses:

AppException (Base)

NotFoundException

UnauthorizedException

ForbiddenException

ValidationException

BusinessLogicException

QuotaExceededException

Best Practices

1. Handle Errors Gracefully

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 429:
        # Handle rate limit
        time.sleep(60)
        return retry_request()
    elif e.response.status_code >= 500:
        # Server error - retry with backoff
        return exponential_backoff_retry()
    else:
        # Client error - log and alert
        logger.error(f"API error: {e.response.json()}")
        raise

2. Log Trace IDs

Always log the trace_id from error responses for debugging and support:

response = requests.post(url, headers=headers)

# Log trace ID from response headers
trace_id = response.headers.get('X-Request-ID')
logger.info(f"Trace ID: {trace_id}")

# If error, trace_id also in response body
if response.status_code >= 400:
    error_data = response.json()
    trace_id = error_data.get('trace_id')
    logger.error(f"Error trace ID: {trace_id}")
    logger.error(f"Error code: {error_data.get('error_code')}")
    logger.error(f"Error message: {error_data.get('message')}")

3. Implement Retry Logic

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=2, max=60)
)
def make_api_request():
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()

4. Monitor Error Rates

Set up monitoring for error patterns:

# Alert if error rate > 5%
if error_count / total_requests > 0.05:
    send_alert("High error rate detected")

Getting Help

If you encounter an error not documented here:

  1. Help Center: zapfeed.io/help
  2. Documentation: zapfeed.io
  3. Email Support: [email protected]

When contacting support, include:

Next Steps