Error Codes

Error envelope

Structured errors on /v1/* generally follow:

{
  "error": {
    "type": "error_type",
    "message": "Human readable description",
    "code": "machine_readable_code"
  }
}

Common mappings

HTTP	Code	Meaning
401	`unauthorized` / `api_key_inactive`	Invalid, missing, or deactivated API key
402	`insufficient_balance`	Wallet too low for estimated charge — add funds
404	`model_not_found`	Unknown model alias
409	`email_already_registered`	Signup: email already in use
422	`validation_error`	Invalid JSON body or parameters
429	`rate_limit_exceeded`	Too many requests for this key
429	`signup_rate_limit_exceeded`	Too many signups from this IP
503	`no_provider_available`	No eligible provider could quote or execute
503	`all_providers_failed`	Execution attempts exhausted

Handling insufficient balance

Retry after a simulated top-up (beta pattern) — production should use your billing provider instead of /v1/balance/add.

import requests

API = "https://api.flopex.ai"
KEY = "sk_live_YOUR_KEY"

def infer(body):
    r = requests.post(f"{API}/v1/inference", headers={"Authorization": f"Bearer {KEY}"}, json=body)
    if r.status_code == 402:
        requests.post(
            f"{API}/v1/balance/add",
            headers={"Authorization": f"Bearer {KEY}"},
            json={"amount_usd": 25.0},
        )
        r = requests.post(f"{API}/v1/inference", headers={"Authorization": f"Bearer {KEY}"}, json=body)
    r.raise_for_status()
    return r.json()