Reading-path month: March 2026. Collection published on September 12, 2026. Months organize the reading path; they are not earlier publication dates.
API errors: a contract for clients and operations
Public responses and internal diagnostics serve different audiences.
Content produced with AI assistance for Thiago Silva’s website. Independent editorial analysis; it does not represent clients or employers.
Reading context
A short architecture article. The technical reference supports the topic; hypothetical scenarios and assessment proposals are editorial analysis, not accounts of personal implementations.
Original source ↗The architecture decision
An unexpected failure must be investigable without turning the user response into an infrastructure map. Error contracts belong in API design.
Practical application
Editorial proposal: define client-friendly categories and an operational correlation identifier. In a hypothetical payment, distinguish business rejection from unavailability, avoiding retry advice that could duplicate a transaction.
How to verify
Simulate dependency failures in testing and review responses, logs and consumer behavior. Confirm investigation is possible through the identifier without receiving secrets. A short message is useful only when matching diagnostics and a clear recovery path exist.