Troubleshoot a failed API request

Start with three checks

1. Confirm that your account has allowance and the plan has not expired.
2. Check the client base URL and avoid adding /v1 twice.
3. Send one short, non-sensitive request and note the error status.

400 · Request format

Check the required fields and supported parameters. Reduce the request to a short text-only example before adding optional features.

401 · Authentication

Check that the key belongs to this service, has not been revoked, and is configured for the correct endpoint. Remove conflicting authentication settings without printing the key.

403 · Permission

Check account and key permissions. Repeating the same request will not resolve a permission restriction.

404 · Path or identifier

Check the base URL, request path and the identifier supported by your account. A missing /v1 or a duplicated /v1 can cause a wrong path.

413 · Request size

Reduce attached content and conversation context, then retry a smaller request.

429 · Allowance or rate limit

Read the returned error message. Check allowance and expiry, reduce concurrency and wait before retrying. A rate limit and an exhausted allowance need different fixes.

500 / 502 / 503 / 529 · Service failure

The service or upstream may be unavailable. Wait and retry a short request with a limited retry count. If the error persists, send its time and status to support.