AI API Failure Triage

Classify the failing boundary

Confirm the exact application, provider, endpoint or API version, model, region, timestamp, attempt, timeout, and request identifier. Separate DNS or connection failure, authentication, authorization, malformed request, unavailable resource, content or safety stop, context limit, quota, rate limit, provider overload, application parsing, and downstream side effects. A provider HTTP response proves connectivity, not end-to-end success.

Do not retry authentication, permission, invalid-request, unsupported-model, or deterministic application-validation failures unchanged. Retry only a classified transient failure within one total budget that includes SDK retries, proxy retries, and application retries. Apply jitter, honor provider guidance, cap concurrency, and preserve an operation ID so a repeated call cannot duplicate a downstream action.

Record a privacy-safe API triage packet

Capture headers and identifiers needed for support while excluding credentials, full prompts, user content, and unrestricted model output. Compare a minimal synthetic request from the same deployment path; do not use a successful request from a different region, account, API surface, or model as proof that the affected boundary is healthy.

Service and operation: [PROVIDER/API/MODEL -> APPLICATION OPERATION ID]
Version and environment: [APP/PROMPT/SDK/API/REGION]
Timestamp and correlation: [UTC -> REQUEST/RESPONSE/TRACE IDS]
Observed failure: [HTTP/STATUS/ERROR/STOP REASON]
Failure class: [NETWORK | AUTH | INVALID | LIMIT | SAFETY | CONTEXT | PROVIDER | APP | DOWNSTREAM]
Sensitive-data review: [REDACTED FIELDS -> AUTHORIZED EVIDENCE]
Total retry budget: [SDK + PROXY + APP -> ATTEMPT/LIMIT]
Minimal synthetic reproduction: [RESULT]
Owner and cadence: [ON-CALL ROLE -> UPDATE INTERVAL]
Stop criteria: [NON-TRANSIENT | BUDGET | COST | SAFETY | UNKNOWN SIDE EFFECT]
Recovery or escalation: [DEGRADE | FAIL CLOSED | RESTORE CONFIG | PROVIDER CASE]
Verification: [USER JOURNEY, POSTCONDITION, AND ERROR RATE]

Expected evidence and verification

Expected evidence includes the classified failure, redacted correlation identifiers, effective configuration, total attempts, minimal reproduction, provider or dependency state, containment decision, and an owner. Verify recovery with the affected route and model, a representative request, application parsing, latency and error-rate observation, and any downstream postcondition.

Stop retries when the failure is non-transient, the shared budget is exhausted, costs or load exceed the boundary, a safety control fires, provider guidance says not to retry, or a prior request may already have caused a side effect. Recovery means reducing load or failing safely, restoring the last verified configuration when a change caused the issue, reconciling uncertain operations, and escalating persistent provider failures with redacted IDs and a timeline.