It is highly desirable in APIs to properly handle errors and provide meaningful error messages, as it can help the API client respond to issues correctly. The default behavior tends to return stack traces that are hard to understand and ultimately useless for the API client. Splitting error information into fields also allows the API client to parse it and provide better error messages to the user. In this article, we’ll cover how to do correct error handling when building a REST API.
Handling error that occur at runtime is quite important. All code is written to be executed under certain conditions, keeping it at runtime. If these conditions are not true, it is expected that the code will not perform the correct actions. If we can’t manage error, the consequences can be significant depending on the type of environment the code is running in.
-
Table of Contents
HTTP status code
The response of the REST API created while creating a REST API must return an informative HTTP Status code response for the client.
So which error codes are used the most?
As seen above, there are many HTTP status codes. But some are more common. These common HTTP status codes have a serious impact on your e-commerce site.
200 Status Code (Success)
If a 200 status code is being sent from the server to the browser, everything is fine. This is the most ideal status code and the user will view your site as it should.
301 Status Code (Permanent Redirect)
301 is one of the most important status codes. It is a code that allows the user to automatically see the new page if the page at a URL is permanently redirected to another page. The content of the new 301-redirected page will be related or similar to the old URL, thus minimizing visitor loss.
302 Status Code (Temporary Redirect)
It is the code that allows a page under testing or maintenance to be temporarily redirected to another page. When a product is out of stock on e-commerce sites, 302 status code is used to show the user the page of another product related to the product in question until the stocks are updated.
403 Status Code (Access Permission Issue)
In response to the request sent by the browser to the server in order to reach a certain page, the 403 status code is used to express that the page in question is banned or that access to the relevant page is not allowed.
404 Status Code (Not Found)
404 is one of the most common error-reporting HTTP status codes users encounter. This code means that the requested page is not found on the requested server. When the URL of a page is changed or the related page is deleted, a screen with the 404 code is sent to the user.
Status Code 410 (Permanently Not Found)
The 410 status code, like 404, indicates that the page to be accessed is not found on the requested server. The difference is that pages with status code 410 are permanently deleted and will not come back. Pages with 404 status codes are often updated and re-accessible. Pages with code 410 are removed from the search engine index after a short while, as they are completely deleted.
500 Status Code (Server Error)
A 500 status code indicates that something is wrong with the server and there is a server-related problem. It is not possible to access the relevant page until the server error that prevents the page from being displayed is resolved.
503 Status Code (Server Unavailable)
Temporary problems on the server are reported with a 503 status code. Servers are temporarily unavailable, mostly due to overload and server maintenance. In addition, cyber attacks against bandwidth can cause this situation.
Logging
Another important topic is record keeping, namely logging. As a matter of fact, logging can be kept not only for error records, but also for transactions -transaction- records made according to the structure of your application, but basically, keeping error records makes your job much easier. No matter how much we test as a developer, users may encounter some fantastic bugs when we release our API into the wild. Most of the time, we are not even given a refund, but even if it is, it is not easy for us to understand the situation or repeat the mistake. It is very important that we keep records for this.
Readable messages for people
There may be situations where the HTTP status codes will be insufficient or we want to provide information to the client in addition to the HTTP status codes. In these cases, a message field can be added to the response model that we will return to the client and it can be filled with the desired message. It is very important that this message is legible and informative.
Enhance Error Handling with APILayer Products
Exchange Rates Data API
If your API works with currency exchange data, perhaps converting amounts or fetching rates, the Exchangerates Data API from APILayer can offer a precise, reliable foundation. It supports real-time, intraday, and historical data, enabling your API to return accurate results or meaningful error feedback when rate data is unavailable or outdated.
Number Verification API
APIs that interact with phone numbers, maybe for account creation or OTP verification, can integrate APILayer’s Number Verification API. It validates both national and international numbers, returning JSON enriched with carrier, location, and line-type info. In your error handling, you can distinguish between “invalid format,” “unassigned number,” or “network error,” providing precise feedback to clients.
By embedding these specialized APIs, you not only improve functionality but also improve your error handling clarity when third-party service responses fail or return unexpected values.
Conclusion
Strong REST API error handling means:
- Using the right HTTP status codes
- Logging smartly and securely
- Crafting structured, descriptive error messages
- Leveraging reliable, domain-specific APIs like Exchangerates Data API or Number Verification API to surface precise error contexts
These practices ultimately lead to better resilience, maintainability, and developer satisfaction.
Frequently Asked Questions
- Why is structured JSON error messaging preferred over plain text?
Structured messages are both machine-parsable and human-legible, enabling clients to programmatically react and users to understand the issue. - How do I choose the right status code for an upstream API failure?
Map it based on severity: use 502 Bad Gateway if the upstream service fails, 504 Gateway Timeout if it’s unreachable, or 503 Service Unavailable for temporary outages. - What additional context should I log alongside error requests?
Include request path, request ID, timestamps, user authentication details (if relevant), and version numbers, without logging sensitive user data. - How can integrating products like Exchangerates Data API improve error handling?
These APIs add clear context, allowing you to signal errors such as “rate data unavailable,” “conversion failed,” or “invalid amount,” rather than generic failures. - Is it okay to expose stack traces in error messages during development?
During development, limited stack trace info can aid debugging. In production, however, suppress detailed traces to prevent information leaks and log them internally instead.
