Common Errors

The most common errors you'll encounter and how to resolve them quickly.

Invalid API Key

Error Code: authentication_failed

Prop

Type

Example:

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "details": {
      "reason": "The provided API key is invalid or has been revoked"
    }
  }
}

Causes:

Prop

Type

Example:

API key is incorrect or has typos
API key has been revoked
Using test key in production or vice versa

Solutions:

Check your API key matches exactly
Verify the key exists in Dashboard → API Keys
Generate a new key if needed

# Common mistake
# client = BrainusAI(api_key="brainus_1234567890")  # Incomplete key

# Correct
# client = BrainusAI(api_key="brainus_1234567890abcdef1234567890abcdef")

Rate Limit Exceeded

Error Code: rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "retry_after": 30
  }
}

Causes:

Sending requests too quickly
Hitting daily or monthly quota
Multiple processes using same API key

Solutions:

<TypeTable
  type={{
    code: {
      description: "Error code identifier",
      type: "string",
      default: "validation_error",
      required: true,
    },
    message: {
      description: "Human-readable error message",
      type: "string",
      default: "Missing required field: query",
      required: true,
    },
    details: {
      description: "Validation error details",
      type: "{ field: string; reason: string }",
      required: false,
    },
  }}
/>

Example:
from brainus_ai import BrainusAI, RateLimitError
import asyncio
import os

async def query_with_retry():
    # async with BrainusAI(...) as client:
    try:
        result = await client.query(query="test", store_id="default")
    except RateLimitError as e:
        print(f"Rate limited. Waiting {e.retry_after}s...")
<TypeTable
  type={{
    code: {
      description: "Error code identifier",
      type: "string",
      default: "store_not_found",
      required: true,
    },
    message: {
      description: "Human-readable error message",
      type: "string",
      default: "Store not found",
      required: true,
    },
    details: {
      description: "Store lookup details",
      type: "{ store_id: string }",
      required: false,
    },
  }}
/>

Example:
        await asyncio.sleep(e.retry_after)
        # Retry

See Rate Limit Errors for detailed handling strategies.

Missing Required Fields

Error Code: validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Missing required field: query",
    "details": {
      "field": "query",
      "reason": "This field is required"
    }
  }
}

Causes:

Forgot to include query parameter
Misspelled field name
Empty string provided

Solutions:

# Missing query
# result = await client.query(store_id="default")  # Error!

# Correct
# result = await client.query(query="What is photosynthesis?", store_id="default")

Store Not Found

Error Code: store_not_found

{
  "error": {
    "code": "store_not_found",
    "message": "Store not found",
    "details": {
      "store_id": "invalid_store"
    }
  }
}

Causes:

Incorrect store_id
Store was deleted
Typo in store name

Solutions:

# Use "default" store for general queries
# result = await client.query(
#     query="What is photosynthesis?",
#     store_id="default"  # Always available
# )

Timeout Error

Error Code: request_timeout

{
  "error": {
    "code": "request_timeout",
    "message": "Request timed out after 30 seconds"
  }
}

Causes:

Network issues
Server overload
Very complex query

Solutions:

# Increase timeout (if SDK allows configuration in constructor)
# client = BrainusAI(
#     api_key=os.getenv("BRAINUS_API_KEY"),
#     timeout=60.0  # seconds
# )

# Or retry
import asyncio
# from brainus_ai.exceptions import TimeoutError

# try:
#     result = await client.query(query="test", store_id="default")
# except TimeoutError:
#     print("Request timed out, retrying...")
#     result = await client.query(query="test", store_id="default")

Server Error (500)

Error Code: internal_server_error

{
  "error": {
    "code": "internal_server_error",
    "message": "An internal server error occurred"
  }
}

Causes:

Temporary server issue
Service degradation
Bug in API

Solutions:

Retry with exponential backoff

import asyncio
# from brainus_ai.exceptions import ServerError

async def retry_on_server_error(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await func()
        except ServerError:
            if attempt == max_retries - 1:
                raise
            wait_time = 2 ** attempt
            print(f"Server error, retrying in {wait_time}s...")
            await asyncio.sleep(wait_time)

# result = await retry_on_server_error(
#     lambda: client.query(query="test", store_id="default")
# )

Check status page: status.brainus.lk
Contact support if persistent: developers@brainus.lk

Network Connection Error

Causes:

No internet connection
Firewall blocking requests
DNS issues

Solutions:

# from aiohttp import ClientConnectionError

# try:
#     result = await client.query(query="test", store_id="default")
# except ClientConnectionError as e:
#     print("Network error:", e)
#     # Check your internet connection

Quick Debugging Checklist

When you encounter an error:

Check the error code and message
Verify API key is correct
Confirm all required fields are provided
Check rate limit headers
Review request payload
Check server status
Enable debug logging

Enable Debug Logging

import logging
from brainus_ai import BrainusAI

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# client = BrainusAI(api_key="brainus_your_key")

# Now you'll see detailed request/response logs
# result = await client.query(query="test", store_id="default")

Still stuck? Email developers@brainus.lk with your error details.

Next Steps

Authentication Errors - API key issues
Rate Limit Errors - Quota handling
Validation Errors - Request validation

On this page