Error Codes Reference

This document provides a complete reference for HTTP status codes and error responses returned by ekoDB's REST API. Understanding these errors helps you handle failures gracefully and troubleshoot issues efficiently.

Error Response Format

ekoDB uses two error response formats depending on the endpoint:

Standard Format (Most Endpoints)

{
  "error": "Human-readable error description"
}

Authentication/Rate Limit Format

{
  "code": 401,
  "message": "Human-readable error description"
}

HTTP Status Codes

Success Codes (2xx)

Code	Name	Description
200	OK	Request succeeded. Response body contains requested data.
201	Created	Resource successfully created (documents, collections, indexes).
207	Multi-Status	Batch operation completed with mixed results. Check individual item statuses.

Client Error Codes (4xx)

400 Bad Request

The request was malformed or contains invalid data.

Common Causes:

Invalid JSON syntax in request body
Missing required fields
Invalid field types or values
Malformed query expressions
Invalid filter operators
Collection name validation failed

Example Response:

{
  "error": "Invalid JSON: expected value at line 1 column 15"
}

Troubleshooting:

Validate your JSON syntax using a JSON linter
Ensure all required fields are present
Verify filter expressions use correct type values (Condition, Logical)
Check operator names are spelled correctly (Eq, Gt, Lt, Gte, Lte, Ne)

401 Unauthorized

Authentication is required or credentials are invalid.

Common Causes:

Missing Authorization header
Expired JWT token (default: 1-hour lifetime)
Invalid API key
Malformed bearer token

Example Response:

{
  "code": 401,
  "message": "Invalid or expired token"
}

Troubleshooting:

Ensure the Authorization: Bearer {TOKEN} header is present
Generate a fresh token if the current one has expired
Verify your API key is valid and has not been revoked
Check for typos in the bearer token

Token Refresh Example:

curl -X POST https://{EKODB_API_URL}/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY"}'

402 Payment Required

Usage limits exceeded for AI/Chat features.

Common Causes:

Chat API usage quota exceeded
AI token limits reached
Billing limits for AI features

Example Response:

{
  "error": "Usage limit exceeded for chat operations"
}

Troubleshooting:

Check your current usage in the ekoDB dashboard
Upgrade your plan for higher AI/Chat limits
Optimize chat prompts to reduce token usage

403 Forbidden

The authenticated user lacks permission for the requested operation.

Common Causes:

Attempting to access a collection without permission
API key lacks required scope
Collection-level access restrictions (writable_fields enforcement)
Admin-only operation attempted with non-admin key

Example Response:

{
  "error": "Access denied: cannot modify fields: email, role"
}

Troubleshooting:

Verify your API key has the required permissions
Check collection permission settings
Contact your administrator if you need elevated access
Review collection_permissions on your API key

404 Not Found

The requested resource does not exist.

Common Causes:

Collection name is misspelled
Document ID does not exist
Endpoint URL is incorrect
Resource was deleted

Example Response:

{
  "error": "Record not found"
}

Troubleshooting:

Double-check the collection name (case-sensitive)
Verify the document ID exists before updating/deleting
Ensure the endpoint URL is correct
List collections to see available resources

429 Too Many Requests

Rate limit exceeded. The client has sent too many requests in a given time window.

Example Response:

{
  "code": 429,
  "message": "Rate limit exceeded. Please try again in 60 seconds."
}

Response Headers:

Header	Description
`Retry-After`	Number of seconds to wait before retrying

Troubleshooting:

Implement exponential backoff retry logic
Respect the Retry-After header value
Batch multiple operations where possible
Consider upgrading your plan for higher limits

Retry Logic Example (JavaScript):

async function retryableRequest(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = parseInt(error.headers.get('Retry-After') || '60');
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

Server Error Codes (5xx)

500 Internal Server Error

An unexpected error occurred on the server.

Example Response:

{
  "code": 500,
  "message": "Internal Server Error"
}

Troubleshooting:

Retry the request after a brief delay
Check ekoDB status page for ongoing incidents
Contact support if the error persists

503 Service Unavailable

The service is temporarily unavailable.

Common Causes:

Ripple (replication) service unavailable
Server maintenance
Server overload

Example Response:

{
  "error": "Service temporarily unavailable"
}

Troubleshooting:

Check ekoDB status page for maintenance windows
Implement retry logic with exponential backoff
Wait a few minutes before retrying

Operation-Specific Errors

Authentication Errors

Scenario	Code	Example Message
Missing API key	401	"API key is required"
Invalid API key	401	"Invalid API key provided"
Expired token	401	"Token has expired"
Malformed token	401	"Invalid token format"

Collection Errors

Scenario	Code	Example Message
Collection not found	404	"Collection 'users' not found"
Invalid collection name	400	"Invalid collection name"
Missing collection name	400	"Collection name is required"

Document Errors

Scenario	Code	Example Message
Document not found	404	"Record not found"
Invalid document data	400	"Invalid document format"
Field permission denied	403	"Cannot modify fields: email, role"

Batch Operation Errors

Batch operations return 207 Multi-Status when some operations succeed and others fail:

{
  "success_count": 8,
  "error_count": 2,
  "results": [
    {"id": "doc1", "status": "success"},
    {"id": "doc2", "status": "error", "error": "Validation failed"}
  ]
}

Transaction Errors

Scenario	Code	Example Message
Transaction not found	404	"Transaction not found"
Transaction expired	400	"Transaction has expired"
Invalid isolation level	400	"Invalid isolation level"

Best Practices

Error Handling Pattern

try {
  const result = await client.insert('users', userData);
} catch (error) {
  switch (error.status) {
    case 400:
      console.error('Invalid request:', error.message);
      // Fix request data and retry
      break;
    case 401:
      console.error('Authentication failed');
      // Refresh token and retry
      await refreshToken();
      break;
    case 403:
      console.error('Permission denied:', error.message);
      // Check permissions
      break;
    case 404:
      console.error('Resource not found:', error.message);
      // Check if collection/document exists
      break;
    case 429:
      console.error('Rate limited, waiting...');
      // Wait and retry with backoff
      break;
    case 500:
    case 503:
      console.error('Server error, retrying...');
      // Retry with exponential backoff
      break;
    default:
      console.error('Unexpected error:', error);
  }
}

Implementing Exponential Backoff

import time
import random

def exponential_backoff_retry(func, max_retries=5, base_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if hasattr(e, 'status_code') and e.status_code in [429, 500, 503]:
                delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
            else:
                raise
    raise Exception("Max retries exceeded")

Logging Error Responses

Always log the full error response for debugging:

match client.query("users", filter).await {
    Ok(results) => { /* handle success */ }
    Err(e) => {
        error!(
            status = %e.status,
            error = %e.message,
            endpoint = "query",
            collection = "users",
            "API request failed"
        );
    }
}

Getting Help

If you encounter persistent errors:

Check the status page - Verify ekoDB services are operational
Review the documentation - Ensure your request format is correct
Search existing issues - Your error may already have a known solution
Contact support - Include the full error response and request details

Support Resources

Documentation: docs.ekodb.io
Support Email: support@ekodb.io

Error Response Format​

Standard Format (Most Endpoints)​

Authentication/Rate Limit Format​

HTTP Status Codes​

Success Codes (2xx)​

Client Error Codes (4xx)​

400 Bad Request​

401 Unauthorized​

402 Payment Required​

403 Forbidden​

404 Not Found​

429 Too Many Requests​

Server Error Codes (5xx)​

500 Internal Server Error​

503 Service Unavailable​

Operation-Specific Errors​

Authentication Errors​

Collection Errors​

Document Errors​

Batch Operation Errors​

Transaction Errors​

Best Practices​

Error Handling Pattern​

Implementing Exponential Backoff​

Logging Error Responses​

Getting Help​

Error Response Format

Standard Format (Most Endpoints)

Authentication/Rate Limit Format

HTTP Status Codes

Success Codes (2xx)

Client Error Codes (4xx)

400 Bad Request

401 Unauthorized

402 Payment Required

403 Forbidden

404 Not Found

429 Too Many Requests

Server Error Codes (5xx)

500 Internal Server Error

503 Service Unavailable

Operation-Specific Errors

Authentication Errors

Collection Errors

Document Errors

Batch Operation Errors

Transaction Errors

Best Practices

Error Handling Pattern

Implementing Exponential Backoff

Logging Error Responses

Getting Help