MEPX
Chapter 3 of 10All chapters
  1. 1What an API is
  2. 2The request
  3. 3The response
  4. 4REST and its alternatives
  5. 5Authentication
  6. 6JSON and data shapes
  7. 7Pagination and filtering
  8. 8Rate limits and retries
  9. 9Versioning and change
  10. 10Calling and debugging APIs

Chapter 3 of 10

The response

Status codes that mean something.

The families

2xx means it worked, 3xx means look elsewhere, 4xx means the request was wrong, and 5xx means the server was. Choosing the right one lets callers handle failures without parsing prose.

  • 401 is not authenticated, 403 is authenticated but not allowed.
  • 422 suits data that parsed but failed validation.

Error bodies

An error should say what was wrong and what would fix it, in a consistent shape with a stable code. A 500 with an HTML page is the worst possible answer to a machine.