What HTTP status code should a REST API return for invalid input?

Use 400 Bad Request for malformed syntax or invalid request shape. Use 422 Unprocessable Entity when the request is syntactically valid but semantically invalid.

What status code should an API return for missing authentication?

Use 401 Unauthorized when authentication is missing or invalid, and include the appropriate WWW-Authenticate challenge when applicable.

What status code should an API return when the user is authenticated but not allowed?

Use 403 Forbidden when the request is understood and authenticated, but the caller is not allowed to perform the action.

REST API Status Code Chooser

Pick the request outcome and this tool suggests the status code a REST API should return.

API outcome

REST API status code rules

Use precise 2xx responses instead of returning 200 for every successful request.
Use 401 for authentication problems and 403 for authorization problems.
Use 404 when the resource is missing or you do not want to reveal whether it exists.
Use 409 for state conflicts, 422 for valid requests with invalid domain data, and 429 for rate limits.
Use 500 only when no more specific 5xx response describes the server-side failure.

Common questions

Should validation errors use 400 or 422?

Use 400 when the request is malformed. Use 422 when the request shape is valid but the submitted domain data cannot be processed.

Should missing authentication use 401 or 403?

Use 401 when the caller is not authenticated. Use 403 when the caller is authenticated but still not allowed.