Skip to content

HTTP Status Codes Reference

Searchable reference of HTTP status codes with plain-English meanings and when APIs should use them.

The five classes

  • 1xx Informational: the request is in progress.
  • 2xx Success: the request worked.
  • 3xx Redirection: the client must go elsewhere or use its cache.
  • 4xx Client error: the request was wrong; retrying unchanged won't help (except 408 and 429).
  • 5xx Server error: the server failed; retrying with backoff may help.

Choosing codes for your API

  • Use 400 for malformed requests and 422 for validation errors in otherwise valid JSON.
  • 401 means "who are you?" and 403 means "I know who you are, and the answer is no."
  • Return 429 with a Retry-After header when rate limiting, so clients can back off politely.
  • Never return 200 with an error message in the body. Clients, monitors and caches rely on the status code.
  • Pair codes with a consistent error body, for example {"error":{"code":"invalid_email","message":"…","hint":"…"}}, or the RFC 9457 Problem Details format.