Skip to main content

​
Error Handling

Learn how to handle errors from the Assisters API gracefully. All errors follow a consistent format to make debugging easier.

​
Error Response Format

All API errors return a JSON response with this structure: 
{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name"
  }
}
FieldDescription
messageHuman-readable description of the error
typeCategory of the error
codeMachine-readable error code
paramThe parameter that caused the error (if applicable)

​
HTTP Status Codes

StatusDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Valid key but no access
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server-side issue
503Service Unavailable - Temporarily overloaded

​
Error Types

​
invalid_request_error

The request was malformed or missing required parameters. 
{
  "error": {
    "message": "Invalid value for 'model': 'unknown-model' is not a valid model",
    "type": "invalid_request_error",
    "code": "invalid_model",
    "param": "model"
  }
}
Common causes:
  • Missing required parameters
  • Invalid parameter values
  • Malformed JSON body
  • Unsupported model name

​
authentication_error

Issues with your API key. 
{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
Common causes:
  • API key is missing
  • API key is malformed
  • API key has been revoked

​
rate_limit_error

You’ve exceeded your rate limits. 
{
  "error": {
    "message": "Rate limit exceeded. Please retry after 5 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}
Additional headers: 
Retry-After: 5
X-RateLimit-Limit-RPM: 100
X-RateLimit-Remaining-RPM: 0

​
tokens_exhausted_error

You’ve used all your monthly tokens. 
{
  "error": {
    "message": "Monthly token limit exceeded. Upgrade your plan or wait for reset.",
    "type": "tokens_exhausted_error",
    "code": "tokens_exhausted",
    "upgrade_url": "https://assisters.dev/pricing"
  }
}

​
insufficient_funds_error

Your wallet balance is too low (for pay-as-you-go). 
{
  "error": {
    "message": "Insufficient wallet balance. Please top up your account.",
    "type": "insufficient_funds_error",
    "code": "insufficient_funds",
    "topup_url": "https://assisters.dev/dashboard/billing"
  }
}

​
content_policy_error

Content was blocked by moderation. 
{
  "error": {
    "message": "Your request was rejected due to content policy violation",
    "type": "content_policy_error",
    "code": "content_filtered"
  }
}

​
server_error

An issue on our side. 
{
  "error": {
    "message": "An internal error occurred. Please try again.",
    "type": "server_error",
    "code": "internal_error"
  }
}

​
Error Codes Reference

CodeStatusDescription
invalid_api_key401API key is invalid or missing
api_key_revoked401API key has been revoked
origin_not_allowed403Request origin not in allowed domains
invalid_model400Specified model doesn’t exist
invalid_request400Request body is malformed
missing_parameter400Required parameter is missing
invalid_parameter400Parameter has invalid value
context_length_exceeded400Input exceeds model’s context limit
rate_limit_exceeded429RPM or TPM limit exceeded
tokens_exhausted429Monthly token limit reached
insufficient_funds402Wallet balance too low
content_filtered400Content blocked by moderation
prompt_injection_detected400Potential prompt injection blocked
model_overloaded503Model is temporarily overloaded
internal_error500Server-side error

​
Handling Errors in Code

from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(
    api_key="ask_your_api_key",
    base_url="https://api.assisters.dev/v1"
)

try:
    response = client.chat.completions.create(
        model="llama-3.1-8b",
        messages=[{"role": "user", "content": "Hello"}]
    )
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
    # Check your API key
except RateLimitError as e:
    print(f"Rate limited: {e}")
    # Wait and retry
except APIError as e:
    print(f"API error: {e}")
    # Handle other errors

​
Retry Strategy

Implement exponential backoff for transient errors: 
import time
import random

def make_request_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise

            # Exponential backoff with jitter
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limited. Retrying in {wait_time:.2f}s...")
            time.sleep(wait_time)

        except APIError as e:
            if e.status_code >= 500 and attempt < max_retries - 1:
                # Retry server errors
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(wait_time)
            else:
                raise

​
Best Practices

Implement Retries

Use exponential backoff for rate limits and server errors

Log Request IDs

Save the X-Request-ID header for debugging with support

Handle All Error Types

Don’t just catch generic exceptions - handle specific error types

Show User-Friendly Messages

Don’t expose raw error messages to end users

​
Getting Help

If you encounter persistent errors:
  1. Check the status page for outages
  2. Review your dashboard for usage limits
  3. Include the X-Request-ID when contacting support
  4. Join our Discord for community help

Contact Support

Email us with your request ID for faster resolution