A housing team must operate Claude beside a case-management API. How should they document failures?

Housing teams operating Claude beside a case-management API should document REST error codes from Claude and the case system together in one runbook. Unified failure documentation works because operators diagnosing a broken housing workflow cannot know a priori whether the fault is model-side (rate limits, auth, timeouts) or case-system-side (validation errors, conflict codes, downstream outages). One runbook maps symptoms to likely sources, retry guidance, escalation paths, and resident-facing messaging so on-call staff recover faster. Capturing Claude token usage metrics in the runbook alongside caseworker shift notes fails by concept: it clutters failure documentation with metrics and staffing notes instead of mapping Claude and case-system error codes to symptoms, retries, and escalation paths. Storing case API error codes in the ticketing backlog while keeping Claude errors in prompt logs fails by concept: it splits failure documentation across two locations, so operators cannot see Claude and case-system codes together in one runbook when diagnosing a broken housing workflow. Recording HTTP status codes for the case API in the developer wiki for release tracking fails by concept: it omits Claude error codes, targets release tracking rather than incident response, and leaves on-call staff without a shared runbook for outage mitigation. Exam caveat: runbooks must stay versioned with the APIs they describe—when Claude or case-management status codes change, update the shared document—and must avoid dumping sensitive case details into public status pages. Operational check: simulate a Claude 429 and a case-API 503 in staging, walk an on-call housing operator through the single runbook, and confirm they select the correct mitigation for each code without asking which system owns the error.