application/problem+json, following RFC 9457.
type, title, status, detail and instance are always present. requestId is present on anything that reached our application. A 422 adds errors, and some types add fields of their own, named on their pages.
Branch on type, never on detail. The slug is stable; the wording may improve.
The type is a real URL.
Open it and it lands on a page for that exact error: what it means, and what to do about it.
Every type has one.
Always quote the requestId
Every response carriesrequestId, in the body on an error and in the X-Request-ID header. It is minted by us and appears in our logs against your call. Quoting it turns a support conversation from a timestamp hunt into a lookup.
If you send your own
X-Request-ID, we echo it back as X-Correlation-ID and log it alongside ours. We never adopt it as our identifier, so the id you quote to support is always one we minted, and two of your calls can never collapse onto one of ours. Your value is echoed only if it is at most 128 printable characters; anything else is dropped silently rather than altered.Common types
Why not-found is uninformative
A resource in another organization, a resource that never existed, and a malformed id all return the same404, byte for byte.
This is deliberate. If they differed, the status code would become a way to test whether a matter exists in someone else’s organization. The cost is that a genuine typo is slightly harder to diagnose; the instance field echoes the path you sent, which is usually enough.
Validation errors
A422 carries an errors[] array:
422 and not a silently dropped value.
The full list
The types above are the ones every integration meets. The rest are the specific not-found and conflict types for one resource, and they read exactly as you would expect:draft-not-found, matrix-not-found, upload-not-completable, review-not-finished.
The capability pages name the ones that particular capability can raise, and the type URL on any problem document lands on that slug’s own page, so there is nothing to look up in a list.
The general rule holds everywhere: a 4xx slug describes something you can fix, and a 5xx slug describes something we have to fix.
There are six 5xx slugs: internal-error (500), web-research-unavailable (502), and the four 503s in the table above.
Nothing in either group is worth parsing out of the detail string.