Contracts for API Designs
An API contract is the agreed shape of every request and response, including field names, types, status codes and the format of errors. Contract design means making payloads consistent and errors machine-readable, for example with problem details, so clients can handle failures without guessing from message text.
Stage: Principles · Part of the API Design roadmap · Last reviewed 19 November 2026
What to learn in Contracts
- Design JSON request and response bodies with consistent naming and types
- Choose correct status codes such as 201, 204, 400, 404, 409 and 422
- Return errors in a standard shape like RFC 9457 problem details
- Represent dates, money and enums in ways that avoid client confusion
- Decide which fields are required, optional or read-only
Contracts interview questions
What should a good API error response contain?
It should carry the right HTTP status plus a stable machine-readable code, a short human message, and where useful the field that failed and a request or trace id. A consistent structure, such as problem details, lets clients branch on the code rather than parse text.
What is the difference between a 400 and a 422 response?
A 400 means the request could not be understood, such as malformed JSON. A 422 means the syntax was fine but the content failed validation, such as an invalid email. Many teams use only 400 for both, so what matters is choosing one convention and documenting it.
Where Contracts fits in the API Design roadmap
Contracts belongs to the Principles stage (beginner level), which takes about 20 hours. Think in resources.
Other units in this stage
Back to the full API Design roadmap