Error Code Reference

This document lists all error codes that the NexusFlow API may return, along with recommended handling approaches.

HTTP Status Codes

Status Code	Name	Possible Causes	Solution
`400`	Bad Request	Request format error Required parameter missing Parameter type mismatch Parameter value outside valid range	Check that the request JSON format is correct, confirm all required parameters are provided with correct types.
`401`	Unauthorized	API key invalid or expired Authorization header not provided Authentication format error	Confirm you are using the correct API key, check that the Authorization header format is 'Bearer sk-air-xxx'.
`403`	Forbidden	Insufficient account balance Insufficient API key permissions Access to prohibited resource Account suspended	Check account balance, confirm the API key has appropriate permissions, contact customer support for account issues.
`404`	Not Found	Requested model does not exist API endpoint path error Resource has been removed	Confirm the model ID spelling is correct, check the API endpoint path, review documentation to verify resource availability.
`413`	Payload Too Large	Request body exceeds size limit Uploaded file too large Messages array too long	Reduce request body size, compress or split large files, reduce conversation history length.
`422`	Unprocessable Entity	Parameter semantic error temperature exceeds 0-2 range max_tokens exceeds model limit	Check that parameter values are within valid ranges, refer to documentation for each parameter's constraints.
`429`	Too Many Requests	Exceeded RPM (requests per minute) limit Exceeded TPM (tokens per minute) limit Too many concurrent requests	Implement request retry mechanism (exponential backoff), upgrade plan for higher quota, optimize request frequency.
`500`	Internal Server Error	Server internal error Upstream model service abnormal System temporary fault	Retry the request after a brief wait. If errors persist, contact technical support.
`502`	Bad Gateway	Gateway error Upstream service unreachable Network link issue	Retry after a brief wait, check service status page; if errors persist, contact technical support.
`503`	Service Unavailable	Service temporarily unavailable Server overloaded Maintenance in progress	Wait a few minutes and retry, follow official announcements for maintenance schedules.
`504`	Gateway Timeout	Request processing timeout Model response too slow Network latency too high	Reduce max_tokens parameter, simplify input content, or retry after a brief wait.

Business Error Codes

When a request fails, the response body includes detailed error information:

{
  "error": {
    "code": "insufficient_quota",
    "message": "You have exceeded your quota. Please check your plan and billing details.",
    "type": "invalid_request_error"
  }
}

Error Code	Description	Solution
`invalid_api_key`	API key format incorrect or does not exist	Obtain a valid API key from the dashboard
`insufficient_quota`	Insufficient account balance or quota exhausted	Add balance to your account or wait for quota reset
`model_not_found`	The specified model ID does not exist	Check the model ID spelling, refer to documentation for available model list
`context_length_exceeded`	Input content exceeds the model's context length limit	Reduce input content length, or use a model that supports longer context
`content_filter`	Content was filtered due to security policy	Modify input content, avoid sensitive or policy-violating content
`rate_limit_exceeded`	Request frequency exceeds the limit	Reduce request frequency, implement retry mechanism
`server_error`	Server internal processing error	Retry after a brief wait; if errors persist, contact support

Error Handling Best Practices

It is recommended to implement exponential backoff retry mechanisms in production environments to gracefully handle temporary errors:

from openai import OpenAI
import time

client = OpenAI(
    api_key="sk-air-your-key",
    base_url="https://nexusflow.vip/v1",
)

def call_with_retry(messages, max_retries=3):
    """API call with retry mechanism"""
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="qwen3.5-plus",
                messages=messages,
            )
            return response
        except Exception as e:
            error_code = getattr(e, 'status_code', None)
            
            # Retriable errors
            if error_code in [429, 500, 502, 503, 504]:
                wait_time = (2 ** attempt) + 1  # exponential backoff
                print(f"Error {error_code}, retrying in {wait_time}s...")
                time.sleep(wait_time)
                continue
            
            # Non-retriable errors
            raise e
    
    raise Exception("Max retries exceeded")

# Usage example
try:
    response = call_with_retry([
        {"role": "user", "content": "Hello!"}
    ])
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Failed: {e}")

Important Notes

Retriable errors: 429, 500, 502, 503, 504 are typically temporary issues; it is recommended to use exponential backoff retry
Non-retriable errors: 400, 401, 403, 404, 422 typically require modifying the request before it can succeed
Log recording: It is recommended to log the request ID (from the X-Request-ID response header) for troubleshooting
Monitoring alerts: It is recommended to set up monitoring alerts for 5xx errors to promptly detect service anomalies