API Reliability
API Error Response Design Guide
Design stable API error responses with machine-readable codes, safe messages, field details, correlation IDs and retry guidance. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Choose the HTTP status | Use transport semantics to separate invalid input, authentication, conflicts, limits and server failures. |
| Add a stable code | Clients should branch on a documented code, not a translated human message. |
| Include safe context | Field-level details and correlation IDs help debugging without exposing stack traces. |
| Document recovery | Say whether callers should fix input, refresh credentials, retry later or contact support. |
Starter snippet
status + stable code + safe message + field details + correlation id + retry hintReview checks
- Keep the envelope consistent across services.
- Do not expose SQL, filesystem paths or internal exceptions.
- Return correlation IDs in both body and logs.
- Document which errors are safe to retry.
Common mistakes
- Returning HTTP 200 with an error flag.
- Using one generic message for every validation field.
- Changing public error codes during copy edits.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Rest Api Error Response Guide, Api Correlation Id Logging Guide, Api Request Body Validation Guide.