Errors and retries
Classify failures and recover without hiding permanent problems or duplicating side effects.
Working scaffold: Status codes, error objects, retry headers, and retryable conditions must be replaced with the verified ONE contract.
Classify the failure
Separate problems the caller can fix from problems that may resolve on their own:
| Category | Typical next step |
|---|---|
| Invalid input or unsupported option | Correct the request; do not retry unchanged |
| Missing or invalid credentials | Verify credential configuration and access |
| Rate or quota limit | Follow the documented reset or retry guidance |
| Timeout or transient service failure | Retry only when safe and within a bounded policy |
| Downstream/provider failure | Follow the documented routing or escalation behavior |
These categories are conceptual; use the actual error codes and response fields from the API reference.
Use bounded retries
For eligible transient failures, use a finite attempt limit and exponential backoff with jitter. Respect any documented retry-after signal. Avoid retry storms and do not automatically retry non-idempotent actions unless duplicate execution is prevented.
Preserve diagnostic context
Record a request identifier and the minimum non-sensitive details needed to debug an issue. Never log credentials. Avoid storing full prompts or responses unless the platform's data policy and the user's purpose allow it.