Error handling is not something most developers enjoy thinking about, but it is a critical part of designing a good API. An API error code is a short, standardized signal that tells a calling application (and the developer behind it) what went wrong and, ideally, how to fix it. When developers write code that interacts with an API, they need to convert these signals into messages that their own apps and users can actually understand.
Different APIs are built on different technologies and libraries, which is why error codes are often duplicated or unrecognizable to the framework used by the consumer. It gets even worse when an error passes through the application without proper handling and reaches end-users who have no idea what it means. This challenge becomes more noticeable when connecting to several eCommerce platforms at once, since each store's backend can return errors in a slightly different way — see how API2Cart handles store connectivity across different eCommerce platforms for an example of unifying such differences behind a single interface.
Making sure your API error codes are clear for its consumers does not require much invention. If you're providing a REST API, users expect that your endpoints behave like any other HTTP endpoint. So it's best to follow established standards rather than build your own from scratch.
A Few Tips for Better API Error Codes
The first tip is to use general HTTP status codes. There are more than 70 of them, but most developers don't have them all memorized. If you choose status codes that aren't very common, users will have to search the web to figure out what you're trying to tell them. That's why most API providers rely on a small, consistent set — typically 8 to 10 status codes.
There are only three possible outcomes in the interaction between an app and an API. Among them, the protocol defines two main classes of error codes:
- The application did something wrong - codes starting with 4 (e.g. 400, 401, 403). They are intended for cases in which the client has erred, and the payload should present a solution to the problem.
- The API did something wrong - codes starting with 5 (e.g. 500, 503, 504). They indicate cases when the server does not handle the call correctly, and the payload should provide details on whether the issue is temporary or permanent.
In both cases, the HTTP protocol defines that servers “should include an entity containing an explanation of the error situation, and indicate whether it is a temporary or permanent condition”.
However, there are cases where a specific API error cannot be fully described by common HTTP status codes. In such cases, it's best to include the error details in the payload while still using a general HTTP 400 or 500 status code. The payload format can be JSON or XML, depending on the MIME (Multipurpose Internet Mail Extensions) type your API uses. This approach matters even more when syncing large volumes of data, for example when using batch operations and pagination for high-volume eCommerce data sync, where a single request may affect many records and needs a clear, structured error response so developers can quickly identify which records failed and why.
Another hint worth mentioning: don't reply with a generic 404 to every call made to a non-existent API endpoint or a missing method. Why? Because doing so sends back the general “Not Found” HTML page, which doesn't make sense when there's no human on the other side of the call. In such situations, it's better to reply with a 404 but using a body your caller can parse (JSON or XML). An even better solution is to reply with a 501 (Not Implemented) if the method truly isn't implemented. If it's implemented but not available for a specific resource, it's better to reply with a 405 (Method Not Allowed), indicating that the request method is not allowed for the requested resource.
What About Error Format?
Choosing an error format that is completely understandable for API users is essential if you want the API you're building to be considered a good one. Let's consider one of the existing types of error format:
{
"error_type": "Application Error",
"error_details": "#500: Internal server error"
}
It is not a bad error format, but it can be a bit hard to use in practice. Below is a clearer, more informative way an error can be presented.
{
"http_code": "401",
"message" : "Authentication needed",
"internal_error_code" : "128",
"details_url" : https:// example.com/errors/128
}
Conclusion
Well-defined error codes and a consistent error format make life easier for everyone who consumes your API, from developers to end-users who see the results of a failed call. Following established standards and keeping the developer experience in mind is what separates a good API from a great one. This consistency matters even more when integrating with multiple eCommerce platforms, where reliable error handling alongside features like real-time store data sync via webhooks helps keep applications stable and predictable.
Marketing manager, API fan, nerd, perfectionist, British humour enthusiast, literature and history geek.
