Skip to main content

​
Error Response Format

All errors follow a consistent format: 
{
  "error": "error_code",
  "message": "Human-readable description",
  "details": {}
}

​
HTTP Status Codes

CodeErrorDescription
400bad_requestInvalid parameters or missing required fields
401not_authenticatedMissing or invalid Authorization header
401token_expiredAccess token has expired — refresh it
402insufficient_tokensYour token balance is zero
403insufficient_planFeature requires a higher subscription
404not_foundGeneration ID or model not found
422validation_errorRequest body fails schema validation
429rate_limit_exceededToo many requests — see rate limits
500provider_errorUpstream AI provider returned an error
503model_unavailableModel is temporarily down

​
Common Errors

​
401 — Token expired

Access tokens expire after 15 minutes. Refresh automatically: 
import requests

class NeuralBoxClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
    
    def request(self, method: str, path: str, **kwargs):
        headers = {"Authorization": f"Bearer {self.api_key}"}
        response = requests.request(
            method,
            f"https://neuralbox.top/api/v2{path}",
            headers=headers,
            **kwargs
        )
        
        if response.status_code == 401:
            # For API key auth, 401 means invalid key
            raise ValueError("Invalid API key")
        
        response.raise_for_status()
        return response.json()

​
402 — Insufficient tokens

{
  "error": "insufficient_tokens",
  "message": "Insufficient token balance. Required: 8, Available: 3",
  "details": {
    "required": 8,
    "available": 3
  }
}
Handle it gracefully: 
try:
    result = client.generate_image(...)
except requests.HTTPError as e:
    if e.response.status_code == 402:
        print("Out of tokens! Top up at neuralbox.top/web/billing")

​
429 — Rate limit exceeded

{
  "error": "rate_limit_exceeded",
  "message": "Hourly limit reached: 100 requests/hour",
  "retry_after": 847,
  "limit_hour": 100,
  "limit_day": 1000
}

​
500 — Provider error

Upstream AI providers occasionally fail. Tokens are never charged on provider errors. 
{
  "error": "provider_error",
  "message": "Provider returned an error. No tokens were charged.",
  "provider": "openai"
}

​
Retry Logic

import requests
import time
from typing import Optional

def make_request(
    url: str,
    headers: dict,
    payload: dict,
    max_retries: int = 3,
    retry_on: tuple = (429, 500, 503)
) -> Optional[dict]:
    
    for attempt in range(max_retries):
        try:
            res = requests.post(url, headers=headers, json=payload, timeout=60)
            
            if res.status_code in retry_on:
                if res.status_code == 429:
                    # Respect Retry-After header
                    wait = int(res.headers.get("Retry-After", 60))
                else:
                    # Exponential backoff for 5xx errors
                    wait = 2 ** attempt
                
                if attempt < max_retries - 1:
                    print(f"Attempt {attempt+1} failed ({res.status_code}), waiting {wait}s...")
                    time.sleep(wait)
                    continue
            
            res.raise_for_status()
            return res.json()
        
        except requests.Timeout:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise
    
    return None

​
Validation Errors

For 422 errors, the response includes field-level details: 
{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": {
    "fields": [
      {
        "field": "size",
        "message": "Value '512x512' is not valid for model dall-e-3. Valid sizes: 1024x1024, 1024x1792, 1792x1024"
      }
    ]
  }
}