Skip to main content

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

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.

Back to the full API Design roadmap