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 and access is denied?

Use 403 Forbidden when the request is understood and the caller lacks permission for the action.

Should an API put errors in a JSON status field?

Use the HTTP status code for the generic result, then put API-specific error details in the response body.

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 the real HTTP status code. A failure returned as 200 OK with a JSON status field looks successful to generic HTTP tooling.
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.

HTTP status codes and JSON error bodies

Use the HTTP status code for the generic result that clients, proxies, logs, caches, and monitoring tools can understand. Use the response body for your application-specific details.

For example, a duplicate email should usually be a 409 Conflict or 422 Unprocessable Entity response with a JSON body that explains the field error. Returning 200 OK with {"status":"error"} makes generic HTTP tooling treat the request as a success.

When the API needs a standard error format, follow the RFC 9457 Problem Details guide and return application/problem+json.

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 needs valid authentication. Use 403 when the caller is authenticated and lacks permission.

Should an API return 200 with a status field for errors?

No. Return the most accurate HTTP status code first. Then include a response body with the error code, field details, or problem information your client needs.