Error Codes

Complete reference for all API error responses and how to handle them.

Error Response Format

All API errors are returned in OpenAI-compatible format:

json

{
  "error": {
    "message": "Human-readable error message",
    "type": "invalid_request_error",
    "code": "error_code",
    "details": {}
  }
}

HTTP Status Codes

Description

Status	Name	Description
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Missing or invalid authentication
`402`	Payment Required	Insufficient balance
`403`	Forbidden	Valid auth but lacking permissions, or security verification failed
`404`	Not Found	Resource doesn't exist
`409`	Conflict	Resource already exists or state conflict
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error
`503`	Service Unavailable	Temporary service issue
`504`	Gateway Timeout	Request took too long

Common Error Codes

Click any error code to see detailed causes, resolutions, and example responses.

HTTP Status Codes

All possible API error responses with their meanings.

StatusTypeCodeDescription

Error Handling

Implement proper error handling to provide a good user experience. Here's a comprehensive error handler:

error_handling.py

import openai
import time

client = openai.OpenAI(
    api_key="your-gonkagate-api-key",
    base_url="https://api.gonkagate.com/v1"
)

def chat_with_retry(messages, max_retries=3):
    """Make API request with exponential backoff retry logic."""
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="Qwen/Qwen3-32B-FP8",
                messages=messages
            )
            return response.choices[0].message.content

        except openai.RateLimitError as e:
            # 429: Wait and retry with exponential backoff
            wait_time = 2 ** attempt
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)

        except openai.AuthenticationError as e:
            # 401: Invalid API key - don't retry
            print(f"Auth error: {e.message}")
            raise

        except openai.BadRequestError as e:
            # 400: Invalid request - don't retry
            print(f"Bad request: {e.message}")
            raise

        except openai.APIStatusError as e:
            # 5xx: Server error - retry with backoff
            if e.status_code >= 500:
                wait_time = 2 ** attempt
                print(f"Server error {e.status_code}. Retrying in {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise

    raise Exception("Max retries exceeded")

# Usage
result = chat_with_retry([{"role": "user", "content": "Hello!"}])
print(result)