Error model intent
Error payloads are operational contracts. Consumers should branch by status, error code, and recoverability class rather than only HTTP code.
Recovery priority
- 4xx input failures: do not retry until payload is corrected.
- 5xx transport failures: retry with jittered exponential backoff and correlation preservation.
- SCIM schema rejections: log raw payload diff and trigger validation gate review.
Incident handoff
Attach error class, endpoint, request ID, and trace identifier whenever escalating; this reduces time to identify whether retries are harmful or required.
Recoverability matrix
| HTTP | Class | Automation action |
|---|---|---|
| 400 | schemaError | Do not retry, fix payload first. |
| 409 | conflict | Compare etag state and perform bounded retry. |
| 429 | rateLimit | Honor Retry-After with backoff and jitter. |
| 500 | intermittentFailure | Retry with preserved idempotency key. |