API Response Status Codes: A Complete Guide for Developers

Introduction

When building or consuming APIs, understanding HTTP response status codes is essential. Status codes provide a standardized way for servers to communicate the result of a client's request. They help developers identify whether a request was successful, whether additional action is required, or whether an error occurred.

HTTP status codes are grouped into five categories:

• 1xx – Informational Responses

• 2xx – Successful Responses

• 3xx – Redirection Messages

• 4xx – Client Errors

• 5xx – Server Errors

This guide covers the most commonly used status codes in modern web applications and REST APIs.

200 OK

The request was successfully processed and the server returned the requested data.

Common Use Cases

• Fetching records

• Updating records

• Successful API calls

Example

{
  "success": true,
  "message": "Data retrieved successfully.",
  "data": {}
}

201 Created

The request was successful and a new resource has been created.

Common Use Cases

• User registration

• Creating products

• Creating orders

Example

{
  "success": true,
  "message": "User created successfully.",
  "data": {
    "id": 101
  }
}

202 Accepted

The request has been accepted but processing has not yet completed.

Common Use Cases

• Background jobs

• Queue processing

• Email sending

• Report generation

Example

{
  "success": true,
  "message": "Request accepted for processing."
}

204 No Content

The request was successful but there is no content to return.

Common Use Cases

• Delete operations

• Logout operations

Example

204 No Content

301 Moved Permanently

The requested resource has been permanently moved to a new URL.

Common Use Cases

• Website migrations

• SEO-friendly URL changes

302 Found

The requested resource is temporarily available at another location.

Common Use Cases

• Temporary redirects

• Login redirection

304 Not Modified

The requested resource has not changed since the last request.

Common Use Cases

• Browser caching

• CDN optimization

400 Bad Request

The server cannot process the request because it contains invalid data.

Common Use Cases

• Missing parameters

• Invalid JSON payload

• Incorrect request structure

Example

{
  "success": false,
  "message": "Invalid request payload."
}

401 Unauthorized

Authentication is required or the supplied credentials are invalid.

Common Use Cases

• Missing token

• Expired token

• Invalid login credentials

Example

{
  "success": false,
  "message": "Unauthorized access."
}

402 Payment Required

The request requires payment before it can be processed.

Common Use Cases

• Subscription-based APIs

• Premium features

• Expired plans

Example

{
  "success": false,
  "message": "Active subscription required."
}

403 Forbidden

The user is authenticated but does not have permission to access the resource.

Common Use Cases

• Role restrictions

• Access control policies

Example

{
  "success": false,
  "message": "Access denied."
}

404 Not Found

The requested resource does not exist.

Common Use Cases

• Invalid URL

• Missing records

• Deleted resources

Example

{
  "success": false,
  "message": "Resource not found."
}

405 Method Not Allowed

The requested HTTP method is not supported by the endpoint.

Common Use Cases

• Using POST instead of GET

• Using DELETE on a read-only endpoint

Example

{
  "success": false,
  "message": "Method not allowed."
}

408 Request Timeout

The server timed out waiting for the client's request.

Common Use Cases

• Slow network connections

• Large uploads

409 Conflict

The request conflicts with existing data.

Common Use Cases

• Duplicate email address

• Duplicate username

• Record already exists

Example

{
  "success": false,
  "message": "User already exists."
}

422 Unprocessable Entity

The request format is valid, but validation rules failed.

Common Use Cases

• Form validation errors

• Invalid email format

• Missing required fields

Example

{
  "success": false,
  "message": "Validation failed.",
  "errors": {
    "email": [
      "Email is required."
    ]
  }
}

429 Too Many Requests

The client has exceeded the allowed request rate.

Common Use Cases

• API rate limiting

• Abuse prevention

Example

{
  "success": false,
  "message": "Too many requests. Please try again later."
}

500 Internal Server Error

An unexpected error occurred on the server.

Common Use Cases

• Application exceptions

• Database failures

• Unhandled errors

Example

{
  "success": false,
  "message": "Internal server error."
}

501 Not Implemented

The server does not support the functionality required to fulfill the request.

Common Use Cases

• Unsupported API features

• Incomplete implementations

502 Bad Gateway

A gateway or proxy server received an invalid response from an upstream server.

Common Use Cases

• Reverse proxy issues

• API gateway failures

• Load balancer problems

503 Service Unavailable

The server is temporarily unavailable.

Common Use Cases

• Maintenance windows

• Server overload

• Infrastructure outages

Example

{
  "success": false,
  "message": "Service temporarily unavailable."
}

504 Gateway Timeout

A gateway or proxy server did not receive a timely response from the upstream server.

Common Use Cases

• Slow APIs

• Database timeouts

• Network issues

Example

{
  "success": false,
  "message": "Gateway timeout."
}

Best Practices for API Responses

1. Use the correct HTTP status code.

2. Keep response formats consistent.

3. Provide clear error messages.

4. Avoid exposing sensitive internal errors.

5. Log server-side exceptions.

6. Use validation errors for user input issues.

7. Implement rate limiting for public APIs.

8. Document all status codes used by your API.

Conclusion

HTTP status codes are the foundation of communication between clients and servers. Proper use of status codes makes APIs easier to integrate, debug, maintain, and scale. By following industry standards and returning meaningful responses, developers can build reliable and user-friendly applications.