Error Message Reference Template (RFC 9457)

Error Message Reference: [Product or API name]

A catalogue of every error your product or API can return: a stable code, the message users see, the cause, the fix and a link to more help. For HTTP APIs, each entry maps to a problem type in the format of RFC 9457, Problem Details for HTTP APIs (July 2023, obsoletes RFC 7807). Replace every [bracketed] value and every row marked Example. The worked example uses a fictional service, the Larkspan Billing API.

Document control

Revision history

1. Purpose and audience

This reference helps three groups:

• Developers integrating the API, who receive an error response and need to know whether to retry, fix the request or contact support.
• End users of applications, who see a message in the interface and follow its "Learn more" link.
• Support staff, who use the code to find the known cause and fix quickly.

Each entry answers four questions in order: what happened, why, what to do now, and where to get more help.

2. Error code scheme

Format: <PRODUCT>-<AREA>-<NNN>, for example BIL-PAY-003.

Rules:

• A code identifies one cause. If two causes need different fixes, they need two codes.
• Never reuse a retired code. Mark it Retired in the catalogue with the date and the replacement code, if any.
• The code appears in the API response, in logs and in the interface (small print is fine), so all three can be matched.

3. Problem details format (HTTP APIs)

Responses use the media type application/problem+json. RFC 9457 section 3.1 defines five standard members; this API uses them as follows.

Extension members (RFC 9457 section 3.2) used by this API:

Clients must ignore extension members they do not recognise (RFC 9457 section 3.2), so you can add members later without breaking them.

Example response:

{
  "type": "https://docs.example.com/errors/BIL-PAY-003",
  "title": "Card declined by the issuer",
  "status": 402,
  "detail": "The card issuer declined payment for invoice INV-20817. No money was taken.",
  "instance": "/requests/7f3c9a2e",
  "code": "BIL-PAY-003",
  "retryable": false
}

When no specific type applies, RFC 9457 section 4.2.1 allows about:blank; the problem then means nothing beyond the HTTP status code. Prefer a specific catalogue type for every error you document. Check the IANA "HTTP Problem Types" registry before inventing a type that may already be registered.

4. Writing rules for entries

1. Title: name the problem, not the code path. "Card declined by the issuer", not "PaymentProcessorException".
2. Detail: say what happened to the user's data. "No money was taken" or "Your changes were saved" removes the worst worry first.
3. Fix: one numbered list of actions the reader can take, in the order they should try them.
4. No blame: describe the input, not the person. "The date is in the past", not "You entered an invalid date".
5. No secrets: never include stack traces, internal host names, SQL, or whether an account exists. RFC 9457 section 5 warns against exposing implementation details.
6. Retry advice: say whether to retry and when, and include the Retry-After header where it is sent.
7. Same words everywhere: the interface message, the title and the catalogue title match.

5. Error catalogue

5.1 Summary

5.2 BIL-PAY-003: Card declined by the issuer (Example)

What happened. The card issuer refused the payment. Larkspan did not charge the card.

Common causes.

• Insufficient funds or credit limit reached.
• The issuer flagged the payment for fraud checks.
• The card is expired or blocked.

How to fix.

1. Ask the customer to use a different card, or to contact their bank.
2. Do not retry the same card automatically; repeated attempts may cause the issuer to block it.
3. If declines affect many customers at once, check the status page at [URL] and contact support with the instance value.

Related. BIL-PAY-001, BIL-PAY-004.

5.3 BIL-VAL-001: Request field is invalid (Example)

What happened. One or more fields failed validation. The errors array lists each field as a JSON Pointer with its own explanation.

How to fix. Correct each field listed in errors and send the request again. The API checks all fields at once, so one response lists every problem.

5.4 [CODE]: [Title]

What happened. [One or two sentences.]

Common causes. [List.]

How to fix. [Numbered steps.]

Related. [Codes.]

6. Handling guidance for clients

• Log code and instance with every failure; support asks for both.
• Never parse detail text in code; it can change and may be localised. Branch on code or type.

7. Governance

8. References

• RFC 9457, Problem Details for HTTP APIs, M. Nottingham, E. Wilde, S. Dalal, July 2023, Proposed Standard, obsoletes RFC 7807: https://www.rfc-editor.org/rfc/rfc9457.
• IANA HTTP Problem Types registry: https://www.iana.org/assignments/http-problem-types.
• WCAG 2.2, success criteria 3.3.1 Error Identification and 3.3.3 Error Suggestion, for interface messages: https://www.w3.org/TR/WCAG22/.
• Related templates: docs/troubleshooting, docs/kb-article, docs/ux-writing-guide, architecture/rest-api-specification, architecture/api-design-guidelines, dev/api-reference.

Standard and licence note

Based on RFC 9457, Problem Details for HTTP APIs (IETF, July 2023), which is freely available; section numbers are cited and the members are described in original wording. This template is original text written for this collection. Check the current RFC status and the IANA registry before relying on them. Template licence: MIT.