The Ultimate Guide to Understanding API Status Codes
An API status code is a three-digit number sent from the server in response to a request made to an API. These codes are a standard part of the HTTP protocol and are used to indicate whether the request was successful, encountered an error, or requires further action.
When working with APIs, understanding API status codes is crucial for developers, admins, and testers. These codes, which are issued by a server in response to a client request, tell you if the request was successful, if there were any errors, and much more. In this article, we'll dive deep into the different types of HTTP status codes and what they mean for your API interactions.
What are API Status Codes?
An API status code is a three-digit number sent from the server in response to a request made to an API. These codes are a standard part of the HTTP protocol and are used to indicate whether the request was successful, encountered an error, or requires further action.
Why Do API Status Codes Matter? API status codes provide immediate feedback to developers, admins, and testers about the outcome of their API requests. Knowing how to interpret these codes can save you time in debugging and help ensure your application runs smoothly.
button
Common API Status Codes You Should Know
Certain API status codes are more common than others. Understanding these can greatly assist in troubleshooting and optimizing your API integrations.
200 OK
The most common status code, 200 OK, indicates that the request was successful. If you see this code, it means your API request went through without any issues.
201 Created
When you send a request to create a resource, a 201 Created status code means your request was successful, and a new resource was created as a result.
400 Bad Request
A 400 Bad Request indicates that the server could not understand the request due to invalid syntax. This often happens when the request body is malformed.
401 Unauthorized
The 401 Unauthorized status code means that the request requires user authentication. Without proper authentication credentials, the request will not be processed.
403 Forbidden
The 403 Forbidden status code tells you that while the server understands the request, it refuses to authorize it. This often happens due to insufficient permissions.
404 Not Found
The 404 Not Found status code is one of the most well-known. It indicates that the server could not find the requested resource, often because the endpoint or URL is incorrect.
500 Internal Server Error
A 500 Internal Server Error is a general error message when the server encounters an unexpected condition. This is usually a problem on the server side, not with the request itself.
5 Types of HTTP Status Codes
HTTP status codes are divided into five categories, each starting with a different digit. Let’s explore what each of these categories represents.
1xx - Informational Responses
The 1xx class includes informational responses, which indicate that the request was received and understood. However, no action is required at this stage.
Complete List of 1xx Status Codes:
100 Continue: The server has received the request headers, and the client should proceed to send the request body.
101 Switching Protocols: The requester has asked the server to switch protocols and the server has agreed.
102 Processing: The server has received and is processing the request, but no response is available yet (WebDAV).
103 Early Hints: Used to return some response headers before final HTTP message.
122 Request-URI Too Long: A non-standard status code used by some servers when the URI is too long.
2xx - Successful Responses
The 2xx status codes indicate that the request was successfully received, understood, and accepted.
Complete List of 2xx Status Codes:
200 OK: The request was successful, and the server returned the requested resource.
201 Created: The request has been fulfilled, and a new resource was created as a result.
202 Accepted: The request has been accepted for processing, but the processing is not complete.
203 Non-Authoritative Information: The request was successful, but the information may be from a cached copy.
204 No Content: The request was successful, but there's no content to return in the response body.
205 Reset Content: The request was successful, and the client should reset the document view.
206 Partial Content: The server is delivering only part of the resource due to a range header sent by the client.
207 Multi-Status: The message body contains multiple status codes for different operations (WebDAV).
208 Already Reported: The members of a DAV binding have already been enumerated (WebDAV).
226 IM Used: The server has fulfilled a request for the resource, and the response represents the result of one or more instance-manipulations applied to the current instance.
3xx - Redirection Messages
The 3xx status codes indicate that further action is required to complete the request.
Complete List of 3xx Status Codes:
300 Multiple Choices: The request has more than one possible response, and the user should choose one.
301 Moved Permanently: The requested resource has been permanently moved to a new URL.
302 Found: The resource you requested is temporarily located at a different URL.
303 See Other: The response to the request can be found under another URI using a GET method.
304 Not Modified: The requested resource has not been modified since the last request.
305 Use Proxy: The requested resource must be accessed through the proxy given by the Location field.
306 Switch Proxy: No longer used, but was meant to indicate that subsequent requests should use the specified proxy.
307 Temporary Redirect: The request should be repeated with another URI, but future requests should still use the original URI.
308 Permanent Redirect: The request and all future requests should be repeated using another URI.
4xx - Client Error Responses
The 4xx codes indicate that the client’s request contains incorrect syntax or cannot be fulfilled.
Complete List of 4xx Status Codes:
400 Bad Request: The server cannot process the request due to a client error.
401 Unauthorized: Authentication is required, and it has failed or has not yet been provided.
402 Payment Required: Reserved for future use, originally intended for digital payment systems.
403 Forbidden: The server understands the request but refuses to authorize it.
404 Not Found: The server cannot find the requested resource.
405 Method Not Allowed: The request method is not supported for the requested resource.
406 Not Acceptable: The requested resource cannot generate content acceptable according to the Accept headers.
407 Proxy Authentication Required: The client must first authenticate itself with the proxy.
408 Request Timeout: The server timed out waiting for the request.
409 Conflict: The request conflicts with the current state of the server.
410 Gone: The requested resource is no longer available and will not be available again.
411 Length Required: The request did not specify the length of its content, which is required.
412 Precondition Failed: The server does not meet one of the preconditions specified in the request.
413 Payload Too Large: The request is larger than the server is willing or able to process.
414 URI Too Long: The URI provided was too long for the server to process.
415 Unsupported Media Type: The request entity has a media type which the server does not support.
416 Range Not Satisfiable: The client has asked for a portion of the file that the server cannot supply.
417 Expectation Failed: The server cannot meet the requirements of the Expect request-header field.
418 I'm a Teapot: An April Fools' joke that became a real status code, indicating the server is a teapot.
419 Page Expired: Used by Laravel Framework when a CSRF token is missing or expired.
420 Enhance Your Calm: Used by Twitter Search and Trends API when the client is being rate limited.
421 Misdirected Request: The request was directed at a server that is not able to produce a response.
422 Unprocessable Entity: The request was well-formed but contains semantic errors.
423 Locked: The resource that is being accessed is locked.
424 Failed Dependency: The request failed because it depended on another request that failed.
425 Too Early: The server is unwilling to risk processing a request that might be replayed.
426 Upgrade Required: The client should switch to a different protocol.
428 Precondition Required: The origin server requires the request to be conditional.
429 Too Many Requests: The user has sent too many requests in a given amount of time.
431 Request Header Fields Too Large: The server is unwilling to process the request because its header fields are too large.
Additional 4xx Status Codes (Non-Standard and Server-Specific):
444 No Response: Used by nginx to indicate that the server has returned no information and closed the connection.
449 Retry With: Used by Microsoft's IIS web server to indicate that the request should be retried after performing an action.
450 Blocked by Windows Parental Controls: Used by Microsoft's family safety software.
451 Unavailable For Legal Reasons: The server is denying access to the resource as a consequence of a legal demand.
460 Client Closed Connection Prematurely: Used by AWS Elastic Load Balancer.
463 Too Many Forwarded IP Addresses: Used by AWS Elastic Load Balancer.
464 Incompatible Protocol: Used by AWS Elastic Load Balancer.
494 Request Header Too Large: Used by nginx when the client sends a header that is too large.
495 SSL Certificate Error: Used by nginx when the client certificate is invalid.
496 SSL Certificate Required: Used by nginx when a client certificate is required but not provided.
497 HTTP Request Sent to HTTPS Port: Used by nginx when an HTTP request is sent to an HTTPS port.
498 Invalid Token: Used by some services to indicate an invalid authentication token.
499 Client Closed Request: Used by nginx when the client closes the connection before the server responds.
5xx - Server Error Responses
The 5xx status codes signify that the server failed to fulfill a valid request.
Complete List of 5xx Status Codes:
500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.
501 Not Implemented: The server does not support the functionality required to fulfill the request.
502 Bad Gateway: The server, acting as a gateway or proxy, received an invalid response from the upstream server.
503 Service Unavailable: The server is currently unable to handle the request due to temporary overload or maintenance.
504 Gateway Timeout: The server, acting as a gateway or proxy, did not receive a timely response from the upstream server.
505 HTTP Version Not Supported: The server does not support the HTTP protocol version used in the request.
506 Variant Also Negotiates: The server has an internal configuration error.
507 Insufficient Storage: The server is unable to store the representation needed to complete the request.
508 Loop Detected: The server detected an infinite loop while processing the request.
509 Bandwidth Limit Exceeded: The server has exceeded the bandwidth specified by the server administrator.
510 Not Extended: Further extensions to the request are required for the server to fulfill it.
511 Network Authentication Required: The client needs to authenticate to gain network access.
CloudFlare-Specific 5xx Status Codes:
520 Web Server Is Returning an Unknown Error: CloudFlare could not parse the response from the origin web server.
521 Web Server Is Down: The origin server has refused the connection from CloudFlare.
522 Connection Timed Out: CloudFlare could not negotiate a TCP handshake with the origin server.
523 Origin Is Unreachable: CloudFlare could not reach the origin server.
524 A Timeout Occurred: CloudFlare was able to complete a TCP connection but did not receive a timely HTTP response.
525 SSL Handshake Failed: CloudFlare could not negotiate a SSL/TLS handshake with the origin server.
526 Invalid SSL Certificate: CloudFlare could not validate the SSL/TLS certificate on the origin web server.
527 Railgun Listener to Origin: Error 527 indicates an interrupted connection between CloudFlare and the origin server's Railgun server.
529 The Service Is Overloaded: Error 529 indicates that the origin server is overloaded.
530 Site Frozen: Error 530 indicates that the requested host name is frozen.
Additional 5xx Status Codes:
561 Unauthorized: Used by some services as an alternative to 401.
598 Network Read Timeout Error: Used by some proxies to signal a network read timeout behind the proxy.
599 Network Connect Timeout Error: Used by some proxies to signal a network connect timeout behind the proxy.
Best Practices for Handling API Status Codes
Implementing Proper Error Handling
When working with APIs, implementing robust error handling based on status codes is crucial for creating reliable applications:
For 1xx Informational Codes:
Continue processing as these are interim responses
Prepare for the actual response that will follow
Use these codes for long-running operations to keep connections alive
For 2xx Success Codes:
Process the response data as expected
For 201 Created, consider retrieving the newly created resource
For 204 No Content, confirm the operation completed without expecting response data
For 3xx Redirection Codes:
Implement automatic redirection for 301 and 302 codes
Update bookmarks or cached URLs for permanent redirects (301, 308)
Handle redirect loops by limiting the number of redirects
For 4xx Client Error Codes:
Validate input data before sending requests to avoid 400 errors
Implement proper authentication mechanisms for 401 errors
Check user permissions and access rights for 403 errors
Verify endpoint URLs and resource identifiers for 404 errors
Implement rate limiting and retry logic for 429 errors
For 5xx Server Error Codes:
Implement retry mechanisms with exponential backoff
Log server errors for debugging and monitoring
Provide user-friendly error messages
Consider circuit breaker patterns for repeated failures
Status Code Monitoring and Analytics
Monitoring API status codes is essential for maintaining healthy API operations.
Key Metrics to Track:
Success Rate: Percentage of 2xx responses vs. total requests
Error Rate: Percentage of 4xx and 5xx responses
Response Time: Average time to receive status codes
Error Distribution: Which specific error codes are most common
Trend Analysis: How status code patterns change over time
Alerting Strategies:
Set up alerts for high 5xx error rates (server issues)
Monitor 4xx spikes that might indicate client integration problems
Track unusual patterns in status code distribution
Alert on response time degradation alongside status codes
Common API Status Code Scenarios and Solutions
Authentication and Authorization Issues
Scenario: Users receiving 401 Unauthorized errors
Solution:
Verify API key or token validity
Check token expiration times
Ensure proper authentication headers are included
Implement token refresh mechanisms
Scenario: Users receiving 403 Forbidden errors
Solution:
Review user permissions and roles
Check API endpoint access controls
Verify subscription or plan limitations
Ensure proper scope in OAuth tokens
Rate Limiting and Performance
Scenario: Receiving 429 Too Many Requests
Solution:
Implement exponential backoff retry logic
Add request queuing mechanisms
Monitor and adjust request rates
Consider upgrading API plans if needed
Scenario: Frequent 504 Gateway Timeout errors
Solution:
Optimize API endpoint performance
Increase timeout configurations
Implement request caching where appropriate
Consider breaking large requests into smaller chunks
Data and Content Issues
Scenario: Getting 422 Unprocessable Entity errors
Solution:
Validate request data format and structure
Check required fields and data types
Ensure business logic validation passes
Review API documentation for data requirements
Scenario: Receiving 415 Unsupported Media Type
Solution:
Verify Content-Type headers
Ensure request format matches API expectations
Check if API supports the media type being sent
Review API documentation for supported formatsCommon API Status Code Scenarios and Solutions
Authentication and Authorization Issues
Scenario: Users receiving 401 Unauthorized errors
Solution:
Verify API key or token validity
Check token expiration times
Ensure proper authentication headers are included
Implement token refresh mechanisms
Scenario: Users receiving 403 Forbidden errors
Solution:
Review user permissions and roles
Check API endpoint access controls
Verify subscription or plan limitations
Ensure proper scope in OAuth tokens
Rate Limiting and Performance
Scenario: Receiving 429 Too Many Requests
Solution:
Implement exponential backoff retry logic
Add request queuing mechanisms
Monitor and adjust request rates
Consider upgrading API plans if needed
Scenario: Frequent 504 Gateway Timeout errors
Solution:
Optimize API endpoint performance
Increase timeout configurations
Implement request caching where appropriate
Consider breaking large requests into smaller chunks
Data and Content Issues
Scenario: Getting 422 Unprocessable Entity errors
Solution:
Validate request data format and structure
Check required fields and data types
Ensure business logic validation passes
Review API documentation for data requirements
Scenario: Receiving 415 Unsupported Media Type
Solution:
Verify Content-Type headers
Ensure request format matches API expectations
Check if API supports the media type being sent
Review API documentation for supported formats
Effortlessly Manage API Status Codes with Apidog
Apidog is an all-in-one API tool designed to help you easily create, modify, and monitor API response codes for various scenarios. Whether dealing with client-side or server-side issues, Apidog equips you with the tools to handle them effectively.
button
This guide will show you how to view, create, and edit API response codes, enabling you and your team to fully leverage Apidog's powerful capabilities.
Viewing API Response Codes in Apidog
With Apidog, you can easily view potential responses that a server might return.
1. Select the endpoint: Choose the endpoint whose response you'd like to inspect. In the image above, the selected endpoint is "Find pet by ID".
2. View the API Responses: Click on "Edit" button above the request address bar, as shown in the image. Scroll down to the "Responses" section to view the various API response codes and their descriptions.
Response codes in this example include OK (200), Record Not Found (404), and Invalid Input (400). Response codes may vary depending on the HTTP method used. For more insights, check out our help docs on Request Methods.
Additionally, Apidog allows you to generate corresponding JSON response codes automatically through file imports, speeding up the API development process and increasing success rates.
Creating Custom API Response Codes in Apidog
Apidog also enables you to customize response codes for different scenarios that might arise during client-server interactions. By clearly identifying whether the issue is on the client or server side, developers can quickly address the problem.
1. Add Response Code: Locate the "+ Add" button next to the API response codes. Select "Add Blank Response" to bring up a pop-up.
2. Enter Details: Provide a name for the response code and the corresponding HTTP status code. Use intuitive names and codes to ensure clarity.
Mastering API status codes is more than just knowing what each number means—it’s about building reliable, efficient, and user-friendly applications. By understanding and correctly handling responses, you can save time debugging, improve error management, and deliver smoother API integrations.
With tools like Apidog, managing and simulating API responses becomes much easier, allowing developers, testers, and product teams to collaborate effectively. Whether you’re troubleshooting errors, monitoring performance, or defining custom responses, having the right approach to status codes will keep your APIs resilient and your applications running seamlessly.
In short, learning API status codes isn’t optional—it’s a vital skill for anyone working with APIs.
