Troubleshooting Guide

This guide covers common issues and their solutions when working with NeuraSutra API Management.

Connection Issues

Cannot Connect to Server

Symptom: ConnectionRefusedError or Connection refused

Solutions:

1. Verify the server is running:

   curl http://localhost:8000/api/v1/health
   

2. Check if the port is correct in your client configuration
3. Ensure no firewall is blocking the port
4. For Docker deployments, verify container is running:

   docker compose ps
   

Timeout Errors

Symptom: ReadTimeout or ConnectionTimeout

Solutions:

1. Increase client timeout for large requests:

   response = requests.post(url, json=payload, timeout=120)
   

2. For image generation, use longer timeouts (30-60s)
3. Check server logs for processing delays

Authentication Errors

Invalid API Key

Symptom: 401 Unauthorized with INVALID_API_KEY

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key"
  }
}

Solutions:

1. Verify API key is included in header:

   headers = {"X-API-Key": "sk_your_key"}
   

2. Check key hasn't been deactivated in admin dashboard
3. Ensure key has correct prefix (sk_)
4. Regenerate key if compromised

API Key Expired

Symptom: 401 Unauthorized with API_KEY_EXPIRED

Solutions:

1. Check key expiration in admin dashboard
2. Generate a new key
3. Update key in your application

Rate Limiting

Rate Limit Exceeded

Symptom: 429 Too Many Requests

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Hourly cost limit exceeded",
    "details": {
      "period": "hourly",
      "current": 5.12,
      "limit": 5.0,
      "reset_at": "2025-01-15T15:00:00Z"
    }
  }
}

Solutions:

1. Wait until the reset time
2. Request limit increase from admin
3. Implement exponential backoff:

   import time
   
   def request_with_backoff(func, max_retries=5):
       for attempt in range(max_retries):
           result = func()
           if result.get("error", {}).get("code") != "RATE_LIMIT_EXCEEDED":
               return result
           wait = 2 ** attempt  # 1, 2, 4, 8, 16 seconds
           time.sleep(wait)
       return result
   

Approaching Rate Limit

Symptom: Response includes warnings

{
  "status": "success",
  "warnings": ["Approaching hourly limit: 85% used ($4.25 of $5.00)"]
}

Solutions:

1. Monitor usage more frequently
2. Reduce request frequency
3. Batch requests where possible
4. Set up alerts for warnings

Model Errors

Model Not Found

Symptom: 404 Not Found with MODEL_NOT_FOUND

{
  "status": "error",
  "error": {
    "code": "MODEL_NOT_FOUND",
    "message": "Model 'gemini-unknown' not found or not enabled"
  }
}

Solutions:

1. List available models:

   response = requests.get(f"{API_URL}/services", headers=headers)
   

2. Check model is enabled for your service in admin dashboard
3. Verify model name spelling (case-sensitive)

Model Not Supported for Operation

Symptom: 400 Bad Request with INVALID_MODEL_CAPABILITY

Solutions:

1. Text models can't generate images
2. Image models can't stream
3. Check model capabilities in documentation

Input Errors

Invalid Input Format

Symptom: 400 Bad Request with INVALID_INPUT

{
  "status": "error",
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid input item at index 1: 'type' must be one of: text, image, audio, video"
  }
}

Solutions:

1. Verify input structure:

   inputs = [
       {"type": "text", "name": "input", "content": "..."},
       {"type": "image", "name": "input", "content": "data:image/png;base64,..."}
   ]
   

2. Check type is valid: text, image, audio, video
3. Check name is valid: input, context, reference, metadata

Image Too Large

Symptom: 400 Bad Request with IMAGE_TOO_LARGE

Solutions:

1. Resize image before encoding:

   from PIL import Image
   
   def resize_image(path, max_size=2048):
       img = Image.open(path)
       img.thumbnail((max_size, max_size))
       buffer = BytesIO()
       img.save(buffer, format="PNG")
       return base64.b64encode(buffer.getvalue()).decode()
   

2. Use lower quality JPEG encoding
3. Maximum size varies by model (typically 4-20MB)

Invalid Base64 Encoding

Symptom: 400 Bad Request with INVALID_IMAGE_DATA

Solutions:

1. Verify data URL format: data:image/png;base64,{base64_data}
2. Ensure proper encoding:

   with open("image.png", "rb") as f:
       b64 = base64.b64encode(f.read()).decode("utf-8")
   data_url = f"data:image/png;base64,{b64}"
   

3. Check for truncated base64 string

Provider Errors

Provider API Error

Symptom: 502 Bad Gateway or PROVIDER_ERROR

{
  "status": "error",
  "error": {
    "code": "PROVIDER_ERROR",
    "message": "Google API error: RESOURCE_EXHAUSTED",
    "details": {
      "provider": "google",
      "original_error": "Quota exceeded"
    }
  }
}

Solutions:

1. Provider quota exceeded - check provider dashboard
2. Provider service outage - check status page
3. Invalid provider API key - update in admin dashboard
4. Contact admin to check provider configuration

Content Filtered

Symptom: Response blocked by safety filters

{
  "status": "error",
  "error": {
    "code": "CONTENT_FILTERED",
    "message": "Response blocked by safety filters",
    "details": {
      "reason": "SAFETY",
      "categories": ["HARM_CATEGORY_DANGEROUS_CONTENT"]
    }
  }
}

Solutions:

1. Review and modify your prompt
2. Content policies vary by provider
3. Some models have stricter filters than others

Streaming Issues

Stream Disconnects

Symptom: Stream stops mid-response

Solutions:

1. Implement reconnection logic (see Streaming guide)
2. Check network stability
3. Increase server timeout settings

Missing Final Chunk

Symptom: Usage/cost data not received

Solutions:

1. Ensure you're reading until stream ends
2. Check for network interruption
3. Parse all data: lines in SSE stream

Database Errors

Database Locked

Symptom: 500 Internal Server Error with database lock

Solutions:

1. Enable WAL mode in config:

   database:
     wal_mode: true
   

2. Restart the server
3. Check for orphaned connections

Debugging Tips

Enable Debug Logging

import logging
logging.basicConfig(level=logging.DEBUG)

# Or for requests library
import http.client
http.client.HTTPConnection.debuglevel = 1

Inspect Raw Response

response = requests.post(url, json=payload, headers=headers)
print(f"Status: {response.status_code}")
print(f"Headers: {dict(response.headers)}")
print(f"Body: {response.text}")

Check Request ID

Every response includes a request ID for tracking:

{
  "request_id": "req_abc123xyz",
  "status": "success"
}

Use this ID when reporting issues to admins.

Getting Help

1. Check server logs: docker compose logs backend
2. Review admin dashboard for service status
3. Contact system administrator with:
   • Request ID
   • Timestamp
   • Full error response
   • Steps to reproduce