Error model intent
Error payloads are operational contracts. Consumers should branch by HTTP status, SCIM scimType, recoverability class, and connector health rather than only retrying every non-200 response.
Recovery priority
- 401 token failures: verify the SCIM bearer token source and rotate carefully; do not print the token in diagnostics.
- 400 input failures: fix unsupported filters, missing required fields, invalid PATCH paths, or unsupported password payloads before retrying.
- 409 conflicts: compare existing directory state and uniqueness constraints before replaying creates.
- 501 group boundaries: treat group replacement and deletion as intentionally unsupported through SCIM.
- 5xx backend failures: check FreeIPA/LDAP, database, and connector health before retrying with jitter.
Incident handoff
Attach error class, endpoint, request ID, SCIM resource identifier, and connector health state whenever escalating. Keep bearer tokens, bind credentials, SAML responses, and password material out of tickets and logs.
Recoverability matrix
| HTTP | Class | Automation action |
|---|---|---|
| 400 | invalidSyntax / invalidValue / invalidFilter / invalidPath | Do not retry until payload, filter, or PATCH path is corrected. |
| 401 | authorization failure | Check token configuration and client secret handling; do not retry with the same bad token forever. |
| 409 | uniqueness / conflict | Read existing state, then decide whether to link, update, or stop. |
| 501 | unsupported group mutation | Use FreeIPA/IdM workflow for group replacement or deletion. |
| 502/503 | backend unavailable | Check FreeIPA/LDAP, database, and readiness, then retry only after health recovers. |