Errors and correlation IDs
Problem Details
Section titled “Problem Details”Public API errors use Problem Details-style responses with HTTP status, a stable domain code, correlation ID, and validation details where applicable. Use the code and HTTP status for program logic; treat the human-readable title/detail as presentation text.
- 401: missing or invalid credential.
- 403: insufficient scope or tenant authorization.
- 404: resource not found within the authorized environment.
- 409: state/idempotency conflict or concurrent operation.
- 422: domain transition or validation rule failure.
- 429: rate limit; honor Retry-After when present.
Correlation and safe retries
Section titled “Correlation and safe retries”Return the correlation ID to support staff without exposing secrets. Retry only when the operation’s contract and outcome certainty make it safe. Validation failures should be corrected, not automatically retried unchanged.