0003. The error model¶
- Status: Accepted
- Date: 2026-11-10 (
*APIError); 2026-11-12 (*RefusalError,214771e); 2026-11-14 (ErrNoDocument,6cb5b1a); recorded 2026-11-14 - Deciders: maintainer
Context¶
The server answers a bad request in three shapes: a detail string
(a 400 for a bad IBAN), a detail array of validation issues (a 422
for a malformed request), and, from pain001 0.0.87 (kit 2), a 422 whose
body is a generate response with success: false and the findings. A
server older than 0.0.87 sends that refusal with 200. Error messages
must never carry the rejected input, which is payment data.
Options considered¶
- Return
(status, body, error)from every method and let the caller inspect the body. Flexible, but every caller re-implements the mapping. - One error type per status. Many types, and a 422 can mean two different things.
- One
*APIErrorfor any non-2xx, a*RefusalErrorthat wraps it for a refused Generate, and a sentinel for a 2xx without the document.
Decision¶
Option 3:
*APIError{Status, Detail}for every non-2xx, withDetailText()andIssues()for the twodetailshapes.*RefusalErrorwraps the*APIError(soStatusstays 422 anderrors.Asfinds either) and carries the decodedGenerateResponsewithValidationErrorsandSchemeViolations.ErrNoDocumentfor a 2xx Generate without XML, so a nil error fromGeneratealways comes with the document.Error()strings list issue locations and counts, never values. Transport errors are wrapped with the method and path only.Requestreturns any status as data, not as an error, because the conformance runner must see every response.
Consequences¶
- Callers check
*RefusalErrorbefore*APIError; the examples and the package documentation show that order. - The fuzz targets (
FuzzErrorOmitsRejectedInput,FuzzRefusalOmitsFindings) hold the no-payment-data rule. - A new server error shape lands in
*APIError.Detailas raw JSON, so it is never lost even before the client learns to decode it.