Search code examples
httpapi-designhttp-status-codes

Which HTTP code is most suitable for when an endpoint is "full"?


If you have an endpoint that only a limited number of connections can be open to (think a video call, or a queue for a ticketing site), what's the best HTTP Code to signal to a Client that the endpoint is "full", and they can't join?

I've considered the following, but don't really like any:

  • 423 Locked - This usually means that some other client has temporarily called dibs on the resorce. It seems to be the least bad fit for what I'm doing
  • 429 Too Many Requests - This one usually means the client has sent too many, not that there are too many in general
  • 409 Conflict - This one is usually about merge conflicts on a resource
  • 400 Bad Request - The most general fallback for unprocessable requests, but isn't really correct here. The request was fine, it just was simply too late.

Are there any better options that I have overlooked?


Solution

  • Since 4xx are reserved to a troubleshooting in the client side, you should use 5xx because your filter criteria (or problem) is on server side.

    Most of servers uses 503 Service Unavailable when they are too busy. The documentation about this indicates that is used to: temporary overloading

    For an exhaustive documentation about Status Code see: RFC 2616

    From the RFC:

    10.5.4 503 Service Unavailable

    The server is currently unable to handle the request due to a
    temporary overloading or maintenance of the server. The implication
    is that this is a temporary condition which will be alleviated after
    some delay. If known, the length of the delay MAY be indicated in a
    Retry-After header. If no Retry-After is given, the client SHOULD
    handle the response as it would for a 500 response.

    Note: The existence of the 503 status code does not imply that a server must use it when becoming overloaded. Some servers may wish to simply refuse the connection.