The world of APIs is confusing and fraught with roadblocks. It’s not uncommon to run into errors in your average API use case, and how these errors are handled and communicated to the end user is often a benchmark for a good product versus a mediocre one. Effective error communication is a huge deal, and can be a huge factor for usability and machine digestibility.

This is all made even more complicated when AI agents become API consumers. A strange error message might — with effort — get parsed by a human. But what happens when this error message is fed to an LLM with minimal context? Human developers can read logs, cross-reference docs, and guess at what an error might mean. AI agents, on the other hand, rely entirely on explicit semantics and clear affordances to reason about next steps, and without this, they can behave unpredictably.

Today, we’re going to talk about designing API error messages for AI consumers. We’ll dive into why this is a problem, and how you can create better API error messages using some of the best guidance currently available.

Status Codes Aren’t a Conversation

Perhaps the biggest reason this is an issue in the first place is the fact that HTTP status codes are short and to the point. They give us an idea of the underlying status, sure, and they might bundle some context, but ultimately, they are highly limited in what they can express and how they can aid the end user.

Consider some standard status codes. A 404 tells us something wasn’t found. A 500 tells us something went wrong. While we can add in some context here and there, a status code is naturally limited. For an AI agent trying to reason through a problem — deciding whether to retry, escalate, or change prompts and parsing — status codes offer little to no actionable insight. Worse, they often obscure this insight and context behind a solid wall of “error 500.”

Imagine an AI agent working with an ecommerce API. It gets a 400 Bad Request with little context provided. From the AI viewpoint, this is fundamentally useless. Was the input malformed? Is a required field missing? Did the request violate a business rule? Without deeper context, the agent can’t know whether to retry, change inputs, or try a brand new tactic. While humans can use their lifelong experience to parse out what might be happening, machines are much more targeted and less adept at such an approach.

That’s the problem. So what are some solutions?

Solution 1: Augment Errors with Rich Context

AI agents thrive on structure, and one solution to this problem is to provide augmented error codes with machine-readable rich context payloads. A good pattern here is following IETF’s RFC 7807 Problem Details for HTTP APIs. This approach defines a standard error message format.

For example, in our 400 Bad Request example, we might generate something like this:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/invalid-price",
  "title": "Invalid price format",
  "status": 400,
  "detail": "The 'price' field must be a positive number",
  "instance": "/orders/abc123"
}

This context provides a few key pieces of information. Firstly, it alerts the system that an error of type 400 has occurred. Next, it specifies the direct type: an invalid price, as well as a URI identifier that provides additional contextual information. The title field then lets the AI know that the issue has to do with an invalid price format, and the detail field specifies what the actual malformation issue was. Finally, a status code is delineated clearly as part of the JSON object, and an instance is given to show where the error arose.

This gives a ton more context, and for an AI agent, it provides a place to start problem-solving. Without any of this context, we would need to infer how to fix it. With this error information in hand, the AI agent can directly fix the problem and validate the fix directly in-prompt.

Solution 2: Define a Recovery Path

Humans can guess next steps. They can infer a course of action using their experience and given the data they’ve observed. AI agents aren’t quite at that level yet, and as such, they need much more explicit instructions. If you throw a structured error at an AI agent and then leave it to figure out what to do with that error, you might get a good result, but you might also get wildly hallucinated next steps that break the entire flow.

Accordingly, consider offering AI agents an explicit recovery path. In our example above, what should an AI do to fix the problem? As developers, we look at that error and know immediately the fix is to address why the price was negative, and maybe do some sort of corrective action. For an AI system, this might be as simple as returning text to try a positive number. But what about something more complicated?

Imagine we have a system that has a rate limiter, and our AI agent has been stopped in its tracks because we have gone over the rate limit as defined by the system. We want to let the system know why it has been stopped, but also provide some ways for it to understand its current status.

Luckily, we can use hypermedia to connect these systems for the AI agent. Below is a HATEOAS implementation in JSON with some links that provide context, along with methods to address the core issue.

{
  "type": "https://example.com/probs/rate-limit",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "You have exceeded your rate limit of 100 requests per minute",
  "retry_after": 30,
  "links": [
    {
      "rel": "self",
      "href": "/orders"
    },
    {
      "rel": "retry",
      "href": "/orders",
      "title": "Retry after delay"
    },
    {
      "rel": "status",
      "href": "/rate-limit-status",
      "title": "Check current rate limit usage"
    }
  ]
}

In this example, we still have our core error reporting, but we also now have some links for the agent to follow. The first is an order page where the agent can understand its contextual order within the system. Next, we provide a retry function for the system to replay the order and try again. Finally, we provide a status service to allow the system to check the status of its rate limiting, allowing it to prevent checks while still limited.

This seems simple, but this hypermedia linking gives the AI a lot more context as well as tools to solve its problems and reason about what the best implementation of such a solution would look like.

Solution 3: Semantic Structuring

In many ways, the error message problem arises from the fact that we often have a dichotomy of human-readable and machine-readable code. The reality is that we now sit in an in-between state, where a machine is reading the response, but as a human would. This is something akin to AI-readable code, and as such, we need to find a more structured and semantic solution.

Instead of just dumping error codes or raw text logs into error payloads, we should instead opt for more structured semantic fields to help categorize and respond to errors. For instance, building our error functions to include more direct and useful fields such as trace_id or suggestions would enable us to point the AI to specific solutions for specific use cases.

The following example assumes an AI has hit a problem with invalid fields. This is a complicated case, because you’re referring to invalid data by providing it as data. For the AI system, it needs to keep in mind what data it hallucinates and what data it must reject while ingesting altogether new data into the system. To resolve this, we can provide much more semantically linked data in our fields:

{
  "type": "https://example.com/probs/invalid-field",
  "title": "Invalid field value",
  "status": 400,
  "error_code": "E1007",
  "detail": "The provided category ID does not exist",
  "parameters": {
    "category_id": "xyz123"
  },
  "suggestions": [
    "electronics",
    "books",
    "clothing"
  ]
}

In this case, the invalid field value is stated with all of its context, but additional suggestions are provided to show the AI agent not only some valid suggested IDs, but the types of IDs that exist. If the AI agent passed something like ISBNlist, it will look at this list and detect books — and if you’ve configured and trained your model properly, it should semantically link books to ISBN, thereby improving its understanding and context.

This kind of structure lets AI agents present the user with alternatives, retry with the closest match, or escalate the issue — without guessing.

Solution 4: Enhance Your Error Taxonomy

Finally, API developers should consider what their API taxonomy actually looks like. While HTTP error codes are all well and good, you can also provide specific error codes to users, and by doing so, define specific errors and issues.

Consider the following error codes, all of which could fall under Error 400 Bad Request:

• Missing required field: A required parameter was not passed.
• Invalid format: The parameter format was incorrect.
• Incorrect resource type: The resource of the specified type can’t be found.

To an AI agent, just replying Error 400 isn’t good enough. In some cases, the problem is so specific that even providing semantic content isn’t very helpful. Resolving this can come in the form of a much more specific taxonomic error solution. For instance, we might resolve our incorrect resource type like this:

{
  "status_code": "400 Bad Request",
  "error_message": "Incorrect resource type provided",
  "internal_code": "E4001",
  "doc_uri": "https://docs.example.com/errors/400/E4001",
  "detail": "The provided resource type does not exist",
  "parameters": {
    "category_id": "xyz123"
  },
  "suggestions": [
    "electronics",
    "books",
    "clothing"
  ]
}

}

By more closely mapping the error code to the specific status code, and then providing the additional contextual information, we can create logical routes for the AI agent to follow to resolve its problem. If it knows it’s part of E4001, it can look this up in the documentation by the provided link and understand the taxonomy of the problem — and prevent it from occurring in the future.

Error Handling For AI Agents

AI agents are machines, but they act like humans in some critical ways. As these systems get more complicated and powerful, we will need to be more intentional in our service design, especially when it comes to error handling. Getting this right now, and future-proofing your systems, can be a huge boon to agentic interactions as well as human utilization.