SCIM errors, explained

Host0:00A sync job quarantines itself, and the log says: unable to create team profile fields, with an underscore in every gap. Search the RFC tables for that string and you will find nothing, because it is not from the RFC. It is one provider's own vocabulary, surfacing through an endpoint that speaks SCIM.

Host0:19Reading SCIM errors is a skill of order - SCIM, S, C, I, M, pronounced sim: what happened by class, which rule fired, which implementation said it. Get the order right and most support tickets answer themselves. This is the walkthrough of the error contract: one envelope, two tables, one header, and the provider strings that fit none of them.

Host0:42Section 3.12 defines a single error envelope, and implementers must return it as JSON, never a bare status line. It carries the HTTP status, which is required and, a detail that surprises people, serialized as a JSON string. It carries scimType, optional, which names the specific rule that fired. And it carries detail, optional, a human-readable explanation.

Host1:08Around that envelope sit two tables. Table 8 maps the statuses: 400 for a request that will not parse or violates the schema; 401 for an invalid or missing authorization header; 403 for a valid authentication acting without permission; 404 for a missing resource or endpoint; 409 for version conflicts and refused duplicates; 412 for a resource that changed underneath the write; 413 for bulk limits; 500 and 501 for the provider's own failures.

Host1:39Table 9 lists ten scimType keywords, and all ten live on HTTP 400. Invalid filter, too many, uniqueness, mutability, invalid syntax, invalid path, no target, invalid value, invalid version, and sensitive. Two of them are pure PATCH: invalid path and no target. One is pure privacy: sensitive, the rule against putting personal data in a request URI, where query strings get logged end to end.

Host2:08The status tells you what class of thing happened, and each class names its own fix. Four-hundred: the request was wrong, so fix the body, the filter, or the path. 401 and 403: the credentials are wrong, so fix the token, not the request. 404: the target is wrong, so check your matching, not your syntax. 409 and 412: the state is wrong, so re-read the resource and retry conditionally. 429: the pace is wrong, and we will come back to it. Five-hundred: the provider is wrong, so log it, quarantine the job, and retry later.

Host2:44On a 400, the scimType picks the exact rule. Read in that order, status, then keyword, then detail, the error stops being a string and becomes a diagnosis.

Host2:57Throttling is the case the tables do not cover. It is not a Table 8 row; it arrives as HTTP 429 with a Retry-After header. And the header is where providers diverge, because its format is not pinned to one shape. One provider's client honors it only as integer seconds, waits five minutes when the header is missing or in HTTP-date form, doubles the wait on every failure, and fails the task after ten attempts. Another provider counts writes and reads against separate throttles and surfaces the rejection under its own exception name.

Host3:32Custom strings are the same story. One provider answers an unsupported operation with its own slugged error instead of a scimType. A provisioning connector that pattern-matches only the RFC shapes misreads all of these, and the operational result is a quarantined job with a log line nobody can decode. The reading rule that resolves it: a verbatim provider string is evidence of one implementation at one date, not a second standard. Map it to the nearest table shape as a teaching judgment, label it with the retrieval date, and never treat the mapping as the provider's own statement.

Host4:07Three things to carry. First: the envelope is the contract; status, keyword, detail, in that order, and the ten keywords all live on 400. Second: the status class names the fix. Request, credentials, target, state, pace, provider; six classes, six different next actions, and fixing the body when the token is wrong is how a five-minute issue becomes a day. Third: provider strings are evidence, not standards. Honor Retry-After in the provider's documented format, map custom codes to the nearest RFC shape, and date every mapping. Paste a real response into the error decoder on this site and watch the three layers separate.