Skip to content

HTTP status codes for RESTful APIs

HTTP status codes are utilized in RESTful architectures to communicate the outcome of a client's request. Instead of embedding status information in the response body, the API relies on the standardized HTTP status codes to indicate success, redirection, client errors, or server errors^[600-developer__principle__restful-rule.md].

Success Codes (2xx)

These codes indicate that the request was received, understood, and accepted successfully^[600-developer__principle__restful-rule.md].

  • 200 OK: Indicates that the server successfully returned the requested data^[600-developer__principle__restful-rule.md]. This is typically used in response to GET requests^[600-developer__principle__restful-rule.md].
  • 201 Created: Used when a user successfully creates or modifies data^[600-developer__principle__restful-rule.md]. This is the standard response for successful POST, PUT, or PATCH requests^[600-developer__principle__restful-rule.md].
  • 202 Accepted: Signifies that the request has been accepted for processing, but the processing has not been completed yet^[600-developer__principle__restful-rule.md]. This is common for asynchronous tasks that have been queued in the background^[600-developer__principle__restful-rule.md].
  • 204 No Content: Represents a successful request where the server returns no content body^[600-developer__principle__restful-rule.md]. This is the standard response for a successful DELETE request^[600-developer__principle__restful-rule.md].

Client Error Codes (4xx)

These codes indicate that the client appears to have made an error, such as a malformed request or a lack of authorization^[600-developer__principle__restful-rule.md].

  • 400 Invalid Request: The server cannot process the request due to a client error (e.g., malformed syntax)^[600-developer__principle__restful-rule.md]. This applies to POST, PUT, or PATCH requests where the data is invalid^[600-developer__principle__restful-rule.md].
  • 401 Unauthorized: Indicates that the request lacks valid authentication credentials for the target resource^[600-developer__principle__restful-rule.md].
  • 403 Forbidden: The user is authenticated but does not have the necessary permissions to access the resource^[600-developer__principle__restful-rule.md].
  • 404 Not Found: The server cannot find the requested resource^[600-developer__principle__restful-rule.md].
  • 406 Not Acceptable: The server cannot generate a response matching the list of acceptable values defined in the request's content negotiation headers (e.g., requesting JSON when only XML is available)^[600-developer__principle__restful-rule.md].
  • 410 Gone: Indicates that the resource requested is no longer available and will not be available again^[600-developer__principle__restful-rule.md]. This is similar to 404 but implies the resource was previously present.
  • 422 Unprocessable Entity: Used when the request is well-formed but contains semantic errors, typically occurring during object creation or modification when a validation error occurs^[600-developer__principle__restful-rule.md].
  • 429 Too Many Requests: The user has sent too many requests in a given amount of time, often used for rate limiting^[600-developer__principle__restful-rule.md].

Server Error Codes (5xx)

These codes indicate that the server failed to fulfill a valid request^[600-developer__principle__restful-rule.md].

  • 500 Internal Server Error: A generic error message indicating an unexpected condition was encountered on the server^[600-developer__principle__restful-rule.md]. This prevents the client from determining if the request succeeded^[600-developer__principle__restful-rule.md].
  • [[HTTP Verbs]]
  • [[RESTful API Design]]

Sources

^[600-developer__principle__restful-rule.md]