Errors & Retry
Practical retry rules for async generation and webhook receivers.
Client requests
Retry when:
- request timed out before you received a response
- network connection dropped
- the server returned a retriable
5xx
Use the same Idempotency-Key when retrying a create call.
Error shape and common codes
{"error":{"code":"invalid_request","message":"..."}}| HTTP | Common code | Action |
|---|---|---|
400 | invalid_request, quote_error | Fix model or parameters; do not retry unchanged |
401 | unauthenticated | Check the Bearer API key |
402 | insufficient_credits | Top up or wait for reservations to release; inspect X-Yeehoo-Balance |
403 | scope_forbidden | Grant the required scope or use another key |
404 | model_not_found, task_not_found | Check IDs and team-workspace ownership |
409 | idempotency_conflict | Use a new key for a different request body |
409 | idempotency_in_progress | Follow Retry-After, then retry the same key and body |
429 | rate_limit | Back off and honor Retry-After when present |
5xx | Server error | Retry a limited number of times with the same idempotency key |
Task polling
Treat these separately:
- transport failure: retry the poll
- task failure: inspect the business error payload and decide whether to resubmit
Webhook receivers
If you return non-2xx, Yeehoo will retry until the retry budget is exhausted.
Return 2xx only after:
- signature passes
- request is accepted for internal processing