Practice: The Right Code for Eight Responses

A created booking, a duplicate username, an expired token, a missing permission, a timeout upstream and three more.

Choosing the status code from what happened, and knowing what the client will do with it, is the skill every endpoint needs. For each scenario on a hotel booking API, choose the status code and say who must act next.

POST /bookings creates booking 81.
POST /users with a username that is already taken.
A request with a token that expired an hour ago.
A signed-in guest calls DELETE /hotels/5, which only staff may do.
The gateway waited 30 seconds for the booking service and gave up.
POST /bookings with a check-out date before the check-in date.
DELETE /bookings/81/notes/3 succeeds, with nothing to return.
The whole API is down for planned maintenance for the next ten minutes.

Show the answers

Each scenario, its code, and who acts next
Scenario	Code	Who acts next
Booking created	201 Created, with Location /bookings/81	Client stores the URL
Username taken	409 Conflict	Client chooses another name
Expired token	401 Unauthorized	Client refreshes the token and retries
Guest deletes a hotel	403 Forbidden	Nobody; the guest may not do this
Upstream timeout	504 Gateway Timeout	Server team; the client checks before retrying the POST
Check-out before check-in	422 Unprocessable Content, or 400	Client corrects the dates
Note deleted	204 No Content	Nobody
Planned maintenance	503 Service Unavailable, with Retry-After 600	Client waits and retries

← → move through sections and cards