When using an API, you shouldn’t need to pull out the instruction manual to understand what each response is trying to tell you. APIs and their error responses should be understandable by humans as well as machine-readable, which means they should be self-descriptive as defined by Roy Fielding. There’s no reason an API needs to be limited to generic HTTP requests.

It’s fairly easy to think of what not to do with API error handling. But what should you do? We’ve examined a wide range of different public APIs to find a few of the best real-world API error responses. The examples below should give you some ideas on what model your own API error messages after.

1. Stripe API

Stripe API is one of the most popular payment processing APIs on the market. That makes it worth evaluating to see how they handle their API error messages. Stripe API doesn’t disappoint, as its API error messages are helpful and detailed.

For example, if you make an API request to see all the charges made to an account without an API key, you get the following response.

{
  "error": {
    "message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY'). See https://stripe.com/docs/api#authentication for details, or we can help at https://support.stripe.com/.",
    "type": "invalid_request_error"
  }
}

See how much more useful this is than a simple 4xx or 5xx code, where you’re left guessing what went wrong? Not only does Stripe API’s error message tell you what went wrong, but it also tells you how to fix it.

2. Merge API

Merge API is an API for consolidating many different APIs through a single source. They’ve got extra incentive to deliver quality error messages. Merge API receives API errors from many sources, which then need to be returned in a consistent and understandable way.

For instance, when you query Merge API for a resource that doesn’t exist, you get the following response:

{
    "status": 400,
    "error": "Not Found",
    "message": "The requested resource was not found on this server.",
    "path": "/api/users/5678",
    "timestamp": "2024-10-20T12:34:56Z"
}

By including the path, the user can double-check to make sure they’re querying the right endpoint. Returning the timestamp makes the API error message helpful for debugging and logging as well, allowing a user to check and see if a particular resource was unavailable at a specific time.

3. Instagram API

Instagram has over 2 billion monthly active users. They’ve got even more reason to have in-depth, useful API error messages that are easily understandable by anyone. When a user makes an API request for an image that’s too big to download, they see this response:

{
  "error": 
    {
      "message": "The image size is too large.",
      "type": "OAuthException",
      "code": 36000,
      "error_subcode": 2207004,
      "is_transient": false,
      "error_user_title": "Image size too large",
      "error_user_msg": "The image is too large to download. It should be less than 8 MiB.",
      "fbtrace_id": "A6LJylpZRKw2xKLFsAP-cJh"
   }
 }

This somewhat goes against our comment about not needing an instruction manual to understand an API error message, but it’s also still self-descriptive. The message details what’s gone wrong. The error code and subcode give more details about the problem and how to fix it. This approach can be helpful for an API that does many different things, as the subcodes can be used to identify specific functions that aren’t functioning the way they should.

4. Salesforce API

Salesforce API is currently the most popular collection on Postman, illustrating just how popular this powerful sales and marketing platform is. With so many users conducting so much financially-sensitive business through the API, there’s a need to have detailed, useful API error messages.

Salesforce API doesn’t disappoint, with 14 unique 4xx error messages and three 5xx messages. Yes, many of their error messages are pretty barebones, but having so many different error messages lets users know exactly what’s going wrong, anyway. For example, providing the wrong credentials at login returns a simple 401 error:

{"error_description": "Client authentication failed", "error": "invalid_client"}

Neglecting to format a query properly could return a 428 error, instead:

{"error_description": "The request wasn't executed because it wasn't conditional. Add one of the Conditional Request Headers, such as If-Match, to the request and resubmit it.", "error": "PRECONDITION_REQUIRED"}

5. Reltio API

We’ll finish our list with another connector API, as they have such a wide range of functionality and need to be so specific. Reltio API is a suite of tools for integrating data into one platform, much like Merge API. Reltio is even deeper, though, letting you perform CRUD through a series of APIs.

The Integrate API is the most impressive, as it includes dedicated functions for a wide range of the most popular APIs, tools, and resources. Each of these connectors features its own error codes, as you can see here with this Salesforce Integration:

Error 1020: Invalid request, tenant {tenantId} is forbidden for current user

When you check this error in the Reltio API documentation, it also gives you a solution. This breaks the rule of self-descriptiveness, but it’s more than made up for with the wide range of tools it works with.

Final Words on Great API Error Messages

APIs aren’t limited to returning a simple 503 error. With the ability to deliver resources like JSON or XML comes the possibility of returning detailed documents about what’s going on with an API. API error messages are one of the best manifestations of APIs’ potential in the first place, as Fielding conceived it, preventing users from having to consult the API documentation. API error messages are one of the fastest, simplest, and least expensive ways to boost developer experience and end customer experience.

Of course, it’s important to balance efficiency with security. There’s such a thing as revealing too much with API error messages. It’s important for API developers to keep API security best practices in mind when crafting API error messages, as sensitive information can result in unauthorized users gaining access to a network. The right balance of information and security makes for a better experience for everyone involved with an API.