Rest API Response Standards

When building or consuming REST APIs, HTTP status codes are one of the most important aspects of communication between the server and the client. They tell us whether a request was successful, failed, or requires additional action.

Below is a structured guide to the most common REST API responses, based on typical CRUD operations (Create, Read, Update, Delete).

List – GET

• 200 OK – Returns a list of entities matching the search criteria.
• 200 OK (Empty Array) – Indicates no entities were found, but the request was still successful.

Get Specific – GET

• 200 OK – The requested entity matching the identifier is returned.
• 404 Not Found – No entity was found for the provided identifier.

Create – POST

• 201 Created – A new resource was successfully created. The response may include the created object or its URL in the Location header.
• 400 Bad Request – Invalid request data, often due to validation errors.
• 202 Accepted (Async) – The request is being processed asynchronously. A status URL may be returned for polling.

Update – PUT

• 200 OK – The resource was successfully updated and returned in the response.
• 204 No Content – The resource was successfully updated, but no content is returned.
• 404 Not Found – No resource was found for the provided identifier.
• 400 Bad Request – Invalid request data.
• 202 Accepted (Async) – Update request accepted for asynchronous processing.

Partial Update – PATCH

• 200 OK – The resource was successfully patched and returned.
• 204 No Content – The resource was successfully patched, but no content is returned.
• 404 Not Found – No resource was found for the provided identifier.
• 400 Bad Request – Invalid patch request.
• 202 Accepted (Async) – Patch request accepted for asynchronous processing.

Delete – DELETE

• 200 OK – Resource was deleted successfully. Some APIs may return additional info in the body, but often it’s just empty.
• 202 Accepted (Async) – Deletion request accepted for asynchronous processing.

Generic Responses

• 401 Unauthorized – The user is not authenticated (e.g., no login or missing token).
• 403 Forbidden – The user is authenticated but not authorized to access this resource.
• 405 Method Not Allowed – The HTTP method used is not supported for this resource.
• 500 Internal Server Error – A generic server-side error occurred.

Best Practices

• Always return the most specific status code that reflects the result.
• Use 201 Created only when a new resource is actually created.
• Provide meaningful error details with 400 Bad Request to help clients fix their requests.
• Consider asynchronous processing with 202 Accepted for long-running operations.

Conclusion

Understanding and implementing the correct REST API status codes is crucial for creating reliable, predictable, and developer-friendly APIs. Clients rely on these codes to decide how to handle responses, so using them properly improves both usability and integration.