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 one of the 49 types 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
There are 48 error types in all. Most 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.
The general rule holds everywhere: 4xx slugs describe something you can fix, 5xx and 503 slugs describe something we have to fix, and nothing in either group is worth parsing out of the detail string.