Case study 12 / Systems Architecture
HTTP APIs with predictable errors, retries, and recovery
An API contract practice for method semantics, idempotency, problem details, correlation, validation, and retry behavior across clients and services.
The delivery question
Can an API consumer determine what failed, whether retrying is safe, and what action should happen next?
A reliable answer has to connect user needs, implementation constraints, and observable acceptance checks. The following practice keeps those decisions visible from discovery through handoff.
Delivery method
From guidance to a testable implementation.
Each layer answers a different question: what the standards require, how the team will build it, and what evidence will show that it works.
Interpret the guidance
- Respect HTTP method semantics and explicitly design idempotency for operations that may be retried.
- Use a consistent machine-readable problem format without leaking internal stack or sensitive data.
- Distinguish validation, authentication, authorization, conflict, rate-limit, dependency, and server failures.
Build the practice
- Document request, success, and problem schemas with stable identifiers and examples.
- Introduce idempotency keys or domain-level duplicate protection for retryable non-idempotent workflows.
- Carry safe correlation identifiers across API responses, logs, and traces.
Validate the result
- Contract tests cover every documented status and problem shape.
- Retry tests prove duplicate requests do not create duplicate business effects.
- Consumers can recover without parsing human-readable error text.
Primary references
Read the standards behind the practice.
These sources are maintained by standards bodies, platform owners, or recognized technical organizations. Links open the original material so the reasoning can be independently reviewed.
Apply it to real work
Have a systems architecture requirement?
Share the users, constraints, risks, and current system. The inquiry will open with Web & Platform Development already selected.