CodePark/ questions / Status codes
START PRACTICINGPRACTICE
Backend question · HTTP & API design › Status codes

A client exceeds your API's rate limit. What status code and headers should the response include?

Return 429 Too Many Requests, with a Retry-After header. 429 tells the client it sent too many requests in a given amount of time. So the client should slow down, not treat the error as a bug.

The Retry-After header says when the client can try again. Its value is one of these:

  • a number of seconds, like Retry-After: 30
  • an HTTP date

Well-behaved clients wait that long before they retry. Ideally they also use backoff (a longer wait after each failure) and jitter (a small random extra wait). Jitter stops all clients from coming back at the same moment.

The body should explain the limit, in your normal error format. Many APIs also send headers that show the limit and the remaining quota. Servers also use Retry-After with 503 to signal planned downtime.

  • Return 429 Too Many Requests.
  • Retry-After gives a number of seconds or an HTTP date.
  • Clients should back off and add jitter.
  • The error body should explain the limit.