Error Codes

Error Response Format

When an error occurs, FlowAPI returns a JSON response like this:


{
  "error": {
    "message": "A human-readable description of the error.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Common Error Codes

HTTP status	Error type	Common cause	Recommendation
400	`invalid_request_error`	Malformed request body or invalid parameter values	Validate types and ranges such as `temperature`
401	`invalid_api_key`	Missing, malformed, or invalid API key	Verify the `Authorization` header and active key
403	`permission_error`	Insufficient permissions for the resource	Check account access and plan limits
402	`insufficient_balance`	Account balance is zero or below	Top up credits before retrying
404	`not_found_error`	Unknown model or endpoint	Verify the model ID and request path
429	`rate_limit_error`	Too many requests in a short period	Apply exponential backoff and retry
500	`server_error`	Internal platform error	Retry the request, then contact support if it persists
502	`server_error`	Gateway could not reach upstream services cleanly	Retry after a short delay and inspect request ID
503	`service_unavailable`	Model is temporarily overloaded	Retry after a short delay or switch models
504	`gateway_timeout`	Request took too long to process	Stream responses or raise the client timeout

Retry with Exponential Backoff

For transient errors such as 429, 503, and 504, implement retries with increasing delays:


import time
from openai import OpenAI, RateLimitError
 
client = OpenAI(
    api_key="YOUR_FLOW_API_KEY",
    base_url="https://api.flowapi.net/v1"
)
 
max_retries = 3
for attempt in range(max_retries):
    try:
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except RateLimitError:
        wait_time = 2 ** attempt
        print(f"Rate limited. Retrying in {wait_time}s...")
        time.sleep(wait_time)

Need Help?

If you encounter persistent errors, contact contact@flowapi.net and include the X-Request-ID header value when available.