Handle failures, usage, and retries
Distinguish invalid inputs from temporary failures and incomplete output.
Use the previous examples and test with simulated responses first. Never log API keys or full user documents. Retrying a request can consume more usage and repeating a write tool can duplicate its side effects.
1. Classify by status
400: validate the payload and any spend-limit message. 401: check key validity. 403: check resource and workspace access. 404: check the path or model ID. 429: inspect rate limits, spend caps, and retry-after. 500/529: a temporary service failure may justify a bounded retry. The Worker demo wraps upstream errors as 502 with upstream_status.
2. Retry only when justified
Honor retry-after when present and use limited exponential backoff with jitter for temporary failures. A spend-cap 429 may not have retry-after and should not loop indefinitely. Invalid input, revoked credentials, and missing access require a fix. The plain-fetch downloads fail clearly and do not retry automatically; official SDKs have their own retry policy, which you should configure rather than accidentally doubling.
3. Preserve evidence and detect truncation
Keep the status, safe error category, request-id, elapsed time, and usage. A 200 alone is not success: check stop_reason and tool failures. max_tokens is incomplete output. Streaming can fail after HTTP headers are sent, so production streaming clients must also handle stream error events.
4. Bound the workload
Choose a small output budget, limit tool rounds, validate input size, and separate read tools from write tools. Set spend limits in the Console and monitor actual usage. Tool schemas and results also contribute to token usage; a tool loop is more than one model request. Never label these examples as free unlimited calls.
Practice & self-check
Simulate a 401, a 429 with retry-after, max_tokens, and a failed tool. Explain which cases need correction, retry, or a clearer user message.
When you’re done, take a moment to check:
Read the official sources
CLI instructions checked against official documentation; API examples tested with simulated responses. Product-account walkthroughs were not performed.