Handle the cause, not just HTTP status
| Category | What to do |
|---|---|
| Authentication / permission | Check your key and model scope. Do not automatically retry. |
| Invalid input / unsupported capability | Correct the input. Never silently remove fields. |
| Insufficient credits / cap too low | Review quantity, fallback, and the quote before a new submission. |
| Provider not configured | Expected for preview models. No real successful output is available. |
| Upstream result unknown | Keep the task ID and query; do not recreate the task. |
| Rate limit | Respect Retry-After and use bounded backoff. |
One operation, one idempotency key
Use one stable Idempotency-Key for recovery of a particular request. The fingerprint includes model, normalized input, output_count, fallback, and max_credits. The same key with different business input is a conflict.
Idempotency keys are not API credentials. They prevent duplicate business acceptance, not unauthorized access. A user-requested regeneration is a new operation with a new key.
Give support a traceable ID
Keep request_id, task_id, item_id, timestamp, and a sanitized error. Never send full API keys or provider credentials. Logs show the operation, each result item, its attempts, and the credit outcome.