Understanding Common API Error Codes

Hello! In our last session, we took our first exciting step into the practical world of APIs by using Postman to make a successful request. You saw how sending a GET request to a specific URL returned a 200 OK status and a body full of useful JSON data. This is the ideal scenario—the "happy path" where everything works as expected.

But as you continue your vibe coding journey, you'll inevitably encounter situations where things don't work. The API might return an error, and your app won't get the data it needs. This is a normal part of development, not a sign that you've done something terribly wrong. The key is knowing how to read the signals the server sends back.

In this lesson, we will focus on deciphering those signals. You'll learn to interpret the most common API error codes you'll see when something breaks: 401 (Unauthorized), 404 (Not Found), and 500 (Server Error). Understanding these codes is like learning to read the warning lights on a car's dashboard; they provide the first and most important clue for diagnosing and fixing the problem, empowering you to better guide your LLM assistant.

A Simple Mental Model: "You Messed Up" vs. "We Messed Up"

When an API request fails, the first question to ask is: "Whose fault is it?" Is the problem with the request I sent, or is there an issue with the API service itself? HTTP status codes give you a clear answer.

The entire system of codes can be simplified into a powerful mental model. A great article on API design for developers puts it perfectly.

This "You vs. We" framework is your foundation. When your LLM-generated code fails and you see an error code, you can immediately determine if you need to fix your request (4xx) or if you need to check the API provider's status (5xx).

Let's quickly reinforce this with a short video that explains the concept verbally.

Now, let's look at the specific codes you'll encounter most often. The image below provides a great high-level overview of the different status code categories. We'll be focusing on the red and orange bars: Client and Server errors.

Decoding Client Errors: The 4xx Series

When you see a 4xx error, the server is telling you that the request you sent is flawed in some way. It's your cue to investigate what you're sending.

404 Not Found

This is perhaps the most famous status code, one you've likely seen browsing the web. In an API context, it means the specific URL endpoint you're trying to reach doesn't exist.

• The Analogy: You're trying to send a package to an address that doesn't exist on the map. The postal service can't deliver it because the destination is invalid.
• In Practice: When you see a 404 error in your app, it's almost always a typo in the API URL that you or your LLM assistant used. Your first step should be to go back to the API's official documentation and triple-check the endpoint URL.

This quick animated explanation drives the point home.

401 Unauthorized

This error is directly related to our previous lesson on API keys. It means you are trying to access a protected resource, but you haven't provided valid credentials to prove who you are.

• The Analogy: You're trying to enter an exclusive club, but you either forgot your membership card at home or the one you presented has expired. The bouncer won't let you in until you show valid credentials.
• In Practice: A 401 error is your signal to check your API key. Did you include it in the request? Did you copy-paste it correctly, without any extra spaces? Is it being loaded correctly from your .env file?

This video uses a similar, very effective analogy.

It's also helpful to know about a related code, 403 Forbidden. While 401 Unauthorized means "I don't know who you are," 403 Forbidden means "I know exactly who you are, but you don't have permission to access this." For example, a regular user trying to access an admin-only feature might get a 403.

Decoding Server Errors: The 5xx Series

When you see a 5xx error, you can breathe a small sigh of relief: the problem probably isn't with your code! This is the "We messed up" category, indicating that something went wrong on the API provider's end.

500 Internal Server Error

This is the most generic server error. It's a catch-all for when the server encounters an unexpected condition that prevents it from fulfilling the request.

• The Analogy: You correctly filled out a form and mailed it to a government office. However, once it arrived, their internal processing machine broke down. Your request was perfect, but their system failed.
• In Practice: There's nothing you can do in your code to fix a 500 error. The best course of action is to check the API provider's official status page (e.g., status.anthropic.com, status.openai.com) to see if they are reporting a known outage. Usually, the only thing to do is wait for them to fix it.

From Code to Context: Reading an Error Message

The status code gives you the category of error, but a well-designed API will also send back a JSON object with more details. This is where you find the specific, human-readable clues to solve the problem. Let's look at the documentation for the Claude API, which you might use in your projects.

As a designer, you can appreciate that a good error message is a core part of a good user experience—even when the "user" is a developer. The goal is to provide clarity and a path to resolution, not just to state that something is broken.

Conclusion

You now have a solid framework for understanding and acting on API errors. Instead of being a mysterious dead end, an error code is now your first clue in the debugging process. When an API call fails, you can look at the status code and immediately know whether to check your own request or the API's status page.

Key Takeaways:

• API errors are your friends; they tell you what's wrong.
• The primary distinction is between 4xx errors ("You messed up") and 5xx errors ("We messed up").
• 404 Not Found: Check for typos in the API endpoint URL.
• 401 Unauthorized: Check that your API key is present, correct, and not expired.
• 500 Internal Server Error: The problem is on the API's side. Check their status page and be patient.
• Always look at the JSON body of the error response for a more detailed, human-readable message.

In our previous lessons, we've focused on the standard request-response cycle of APIs. In our next lesson, we'll explore a different communication pattern: WebSockets. You'll learn what they are and why they're essential for building real-time features like live chat or collaborative design tools.