API guides
Errors & rate limits
Classify before retrying
Applications should distinguish request, identity, policy, quota and transient upstream failures. Retrying every non-200 response increases cost and can amplify incidents.
Error classes
Treat invalid requests and authentication failures as caller changes; policy and quota failures as operator decisions; and only classified transient upstream failures as retry candidates.
Rate limits
Respect Retry-After when present, apply jittered backoff and keep all attempts inside one application deadline. Workspace and service-key limits can both apply.
Correlation
Record HTTP status, structured error type, Router request ID, selected route class and terminal state. Keep credentials and content out of routine logs.
Streaming failures
Errors before output may permit Router fallback. Errors after output begins require an incomplete terminal state or visible application recovery; do not concatenate a second provider response invisibly.