📘 Introduction

When working with REST APIs, understanding HTTP status codes is essential for debugging, testing, and building reliable applications.
API error codes help clients and servers communicate the result of a request, whether it was successful, redirected, invalid, or failed due to server issues.

This article provides a complete and practical reference of common API error codes, categorized by type, with real-world scenarios to help developers, testers, and QA engineers quickly identify and fix issues.

            
Common API error codes infographic showing 2xx, 3xx, 4xx, and 5xx HTTP status codes


✅ Success Codes (2xx)

These status codes indicate that the request was successfully received, understood, and processed by the server.

CodeMeaningWhen It Occurs
200OK                            Successful GET, PUT, PATCH, or DELETE request
201Created                                Resource successfully created using POST
202Accepted                            Request accepted for processing (asynchronous operations)
204No Content                            Successful request with no response body (commonly used for                                   delete operations)


🔁 Redirection Codes (3xx)

Redirection codes indicate that the client must take additional action to complete the request, usually by accessing a different URL.

CodeMeaningWhen It Occurs
301Moved Permanently                Resource permanently moved to a new URL
302Found                Temporary redirection
304Not Modified                Resource hasn’t changed (used for caching)
307Temporary Redirect                Temporary redirect while preserving HTTP method
308Permanent Redirect                Permanent redirect while preserving HTTP method


❌ Client Error Codes (4xx)

These errors occur when the client sends an invalid request or lacks required permissions.

CodeMeaningWhen It Occurs
400Bad Request        Invalid JSON, missing required fields, validation errors
401Unauthorized    Missing or invalid authentication credentials
403Forbidden    Authenticated but lacks permission
404Not Found        Resource or endpoint does not exist
405Method Not Allowed    Incorrect HTTP method used
406Not Acceptable    Server cannot produce response as per Accept header
408Request Timeout    Client request took too long
409Conflict    Duplicate or conflicting resource
410Gone    Resource permanently deleted
411Length Required    Missing Content-Length header
412Precondition Failed    Header conditions not met
413Payload Too Large    Request body exceeds allowed size
414URI Too Long    Request URL too long
415Unsupported Media Type    Incorrect or missing Content-Type
422Unprocessable Entity    Valid JSON but business rule validation failed
423Locked    Resource is locked
429Too Many Requests    Rate limit exceeded


💥 Server Error Codes (5xx)

These errors indicate that the server failed to process a valid request.

CodeMeaningWhen It Occurs
500Internal Server Error            Unhandled exception or server crash
501Not Implemented            Feature not supported by server
502Bad Gateway            Invalid response from upstream server
503Service Unavailable            Server down or under maintenance
504Gateway Timeout            Upstream service timeout
507Insufficient Storage            Server out of storage


🤔 Common Confusion: 400 vs 415 vs 422

Understanding the difference between these three error codes avoids incorrect API handling.

CodeScenarioExample
400Malformed request             Invalid JSON syntax, missing required fields
415Wrong Content-Type            Sent text/plain instead of application/json
422Business rule violation       age = -5 (valid format, invalid value)


⚡ Quick Reference by Use Case

🔐 Authentication & Authorization

  • 401 → Not logged in
  • 403 → Logged in but insufficient permission

📦 Resource Handling

  • 404 → Resource does not exist
  • 410 → Resource permanently removed

🧪 Data Validation

  • 400 → Syntax or malformed request
  • 415 → Invalid content type
  • 422 → Business validation error

🚦 Rate Limiting

  • 429 → Too many requests

🖥 Server Issues

  • 500 → Server error
  • 503 → Server unavailable or under maintenance


🏁 Conclusion

Understanding API error codes is critical for building robust applications, writing effective test cases, and troubleshooting production issues.
By correctly handling HTTP status codes, developers and testers can improve API reliability, user experience, and system stability.

Bookmark this guide as your quick reference for common API error codes.


Happy reading !!