Complete AI API Error Handling Guide: 401, 403, 429, 500 Explained

401 Unauthorized

Cause: API Key doesn't exist, was deleted, has expired, or the request header format is wrong (should be Bearer {key}).

• Check that the API Key is correctly pasted
• Confirm the key hasn't been deleted in the dashboard
• Confirm the header is 'Authorization: Bearer xxx' format

403 Forbidden

Cause: insufficient balance, subscription expired, account frozen, or attempting to access a model not enabled on your account.

429 Rate Limit

Cause: rate limit triggered, usually from too many concurrent requests or calls in a short period.

• Add retry logic with backoff (exponential backoff)
• Reduce concurrency
• Consider upgrading your plan for higher rate limits

500 Internal Server Error

Cause: temporary upstream model service error — usually not your code's fault.

• Wait 5-10 seconds and retry
• Check the ChinaWHAPI status page
• Contact support if 500 persists

400 Bad Request

Cause: malformed request body, usually incorrect JSON format, non-existent model name, or missing required fields.

Best Practices

All production code should implement: retry with backoff, timeout control (60-120 seconds recommended), fallback strategy (switch to backup when primary is unavailable), and monitoring alerts.