Error Handling

Handle errors gracefully. HTTP status codes, retries, rate limiting, and idempotency keys.

FairStack uses standard HTTP status codes and provides detailed error responses.

HTTP status codes

Code	Meaning	Action
200	Success	Process the response
400	Bad Request	Check your request parameters
401	Unauthorized	Check your API key
402	Insufficient Credits	Top up your account
429	Rate Limited	Wait and retry with backoff
500	Server Error	Retry with idempotency key

Error response format

{'{'}
  "error": {'{'}
    "code": "insufficient_credits",
    "message": "Not enough credits. Required: $0.025, Available: $0.001",
    "status": 402
  }
}

Idempotency keys

Include an Idempotency-Key header to safely retry requests:

curl -X POST https://api.fairstack.ai/v1/generations/image \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY" \
  -H "Idempotency-Key: req_unique_123" \
  -d '{'{'}"model": "z-image-turbo", "prompt": "test"}'

If you retry the same idempotency key, you get the same response without being charged again.

Retry strategy

Retry 429 and 5xx errors with exponential backoff
Do not retry 400 or 401 errors -- fix the request first
Always use idempotency keys for generation requests
Maximum 3 retries with 1s, 2s, 4s delays

Next steps

Authentication -- API key management
API Reference -- full endpoint documentation

Voice Cloning Overview