The API That Lost Users Taught Me What Actually Matters

I shipped an API once that was technically correct. It had endpoints. It returned data. It had tests. My team called it "done" on a Friday afternoon, and I remember feeling that particular satisfaction of closing a ticket and moving on to the next feature.

Within three months, integration partners were asking for favors. Simple things. Different error formats. Better status codes. Pagination that wouldn't crash their mobile app. I treated these as edge cases—minor inconveniences that shouldn't require my attention when there were "real" features to build. I was wrong. Those partners weren't complaining about the product. They were complaining about me.

Reading about someone else's API failures was humbling because every single mistake they listed, I'd made too. Not all of them, but enough. The difference between shipping code and shipping something people actually want to integrate with is subtle, but it's the difference between a project that grows and one that slowly dies from a thousand small frustrations.

When HTTP Status Codes Are Just a Formality

Here's what I didn't understand early on: HTTP status codes aren't just decoration. They're a contract. When you return 200 with {"success": false}, you're essentially saying "everything is fine, trust me" while handing the consumer a loaded gun and asking them to figure out which part of your response is the trigger.

I watched a partner's integration fail silently because their HTTP client library cached every 200 response. My API was returning 200 for everything—successful requests, validation failures, auth errors, rate limiting. Their cache layer couldn't distinguish between "this user actually doesn't exist" (404) and "this request was malformed" (400). So it cached the error response and served it to thousands of users.

The fix sounds obvious in retrospect: use the right status code. 401 for authentication failures. 422 for validation errors. 429 for rate limits. But understanding why these codes matter—understanding that they're how HTTP clients interpret intent—changed how I think about APIs entirely.

Versioning Is Cheap Insurance

I didn't version my API because "we control both the frontend and backend, so changes are coordinated." That worked fine until they weren't. The moment an external partner integrated with my API, or until my own mobile app was out of my direct control, that assumption became dangerous.

The cost of adding versioning upfront? A few keystrokes. /v1/ instead of /. That's it. The cost of not versioning and breaking production integrations? A Friday night email. Support tickets. Trust eroded. The math is simple.

I maintain two versions now. That's genuinely enough for most scenarios if you have a clear deprecation timeline and a migration guide that doesn't assume users will read your mind.

Rate Limiting: The Feature I Thought Was Optional

This one stung. A user's script—nothing malicious, just buggy code in a retry loop—hammered my database with requests. Everyone else experienced timeouts. I didn't have visibility into what happened until the tickets came in.

Rate limiting isn't a nice-to-have. It's foundational infrastructure. Not because you expect attacks, but because you need to protect your system from mistakes—your own, your users', whoever's.

My Take

I agree with basically everything in the original article, but I want to push on one point: these mistakes aren't really REST mistakes. They're API design mistakes. The author uses REST examples, but the core lesson is that your API is the interface between your system and everyone else's.

That means consistency matters more than cleverness. One error shape, not three. One versioning scheme, not undefined. One rate limit mechanism that actually works. These aren't technical decisions—they're communication decisions.

What I'd add: get feedback from actual integration partners before you ship. Not friends who'll be kind. Real partners building on your API. They'll reveal every assumption you've made wrong.

A Practical Example

Here's how I structure error responses now:

// Every error, same shape
const error = {
  error: {
    code: "validation_error",
    message: "Email is required",
    details: {
      field: "email",
      constraint: "required"
    }
  }
};

// Client code is trivial
if (response.status >= 400) {
  handleApiError(response.body.error);
}

One handler. One shape. One way to think about failures across my entire API surface.

What Would You Do?

I'm curious: have you inherited an API that violated any of these patterns? How much time did you spend working around its quirks before you could fix it? And if you're building APIs now, which of these do you find hardest to discipline yourself on?

Source: This post was inspired by "5 REST API Mistakes That Cost Me Users — and How to Fix Them" by Dev.to. Read the original article