An API is a promise. Every endpoint you publish tells developers, “This is how it works, and it will keep working.” Break that promise, and you don’t just frustrate a few users. You break production systems you’ve never seen. Industry surveys have consistently found that a majority of organizations now treat APIs as revenue-generating products, yet many teams still ship endpoints with no versioning plan, no rate limits, and no consistent error format. The gap between what an API promises and what it delivers is where the most expensive mistakes live.
This article walks through the mistakes that show up again and again in real integrations, why each one bites, and what actually works in practice. The focus is on patterns you can apply today, not abstract theory.
Shipping Without a Versioning Strategy
The single most common mistake is treating versioning as something you’ll “figure out later.” Later arrives the day a breaking change is needed, and by then dozens of clients depend on the current shape of your responses.
There are three mainstream approaches, and each has trade-offs:
| Approach | Example | Best For | Main Drawback |
|---|---|---|---|
| URI path versioning | `/v1/orders` | Public APIs with many consumers | URL churn on every major release |
| Header versioning | `Accept: application/vnd.api+json; version=2` | Internal APIs, clean URLs | Harder to test and debug in a browser |
| Media-type versioning | Custom `Content-Type` | APIs with strong content negotiation | Higher client complexity |
What works in practice: pick URI path versioning for anything public. It’s the least clever option, and that’s the point. Developers can see the version in every log line and curl command. Reserve header-based versioning for internal services where you control every client.
The mistake isn’t choosing the “wrong” scheme. It’s having no scheme at all, then quietly changing field types or removing parameters and hoping nobody notices.
Inconsistent Error Responses
Nothing slows down an integration more than an error body that looks different on every endpoint. One route returns `{“error”: “bad request”}`, another returns `{“message”: “Invalid”, “code”: 400}`, and a third returns a bare string.
The fix is a single, stable error schema across the entire API. The industry standard for this is Problem Details for HTTP APIs, which defines a predictable structure with fields like `type`, `title`, `status`, `detail`, and `instance`. Adopting it means every client error handler can be written once. (HTTP documentation (MDN Web Docs))
Practical tips that make a real difference:
- Always include a machine-readable code alongside the human-readable message.
- Never return a stack trace, database error, or internal hostname in a response body.
- Include a correlation or request ID so support teams can trace a failure end to end.
- Validate input at the edge and return field-level detail instead of only “invalid request.”
A common mistake people make is returning validation errors as a single string. Clients then have to parse prose to figure out which field failed. Return an array of field-level problems instead.
Misusing HTTP Status Codes
HTTP already has a vocabulary for outcomes. Many APIs ignore it. Two patterns are especially damaging: returning `200 OK` with an error payload inside the body, and returning `500` for problems the client caused.
The first pattern breaks monitoring. Every dashboard shows green while users are failing. The second pattern breaks retry logic, because clients reasonably assume a `500` is worth retrying when it was actually a malformed request that will fail forever.
The authoritative reference here is HTTP Semantics, which defines what each status code means. A short working rule set covers most cases:
- `400` for malformed syntax or failed validation
- `401` for missing or invalid credentials
- `403` for authenticated users who lack permission
- `404` for resources that don’t exist (or that the caller shouldn’t know exist)
- `409` for state conflicts, like duplicate creates
- `422` for semantically invalid but well-formed input
- `429` for throttling
- `5xx` only for genuine server faults
Getting these right isn’t pedantry. Caching layers, proxies, client libraries, and observability tools all key off status codes.
Ignoring Idempotency on Writes
Network retries are not optional. Timeouts happen, mobile connections drop, and queue workers redeliver messages. If a `POST` that creates a payment runs twice, someone gets charged twice.
The standard mitigation is the `Idempotency-Key` header pattern, popularized by Stripe and now widely adopted. The client generates a unique key per logical operation, sends it with the request, and the server stores the result against that key. A retry with the same key returns the original response instead of creating a duplicate.
What actually works in practice: store idempotency keys with a TTL (24 hours is common), scope them per customer, and return the same status code and body on replay. A subtle mistake is storing only the key but not the response, which means a replay still executes the operation.
For `PUT` and `DELETE`, the HTTP specification already defines idempotent semantics, so design those methods accordingly rather than treating them like `POST`.
Unbounded or Broken Pagination
An endpoint that returns every record in a collection works beautifully in testing with 50 rows. In production with 500,000 rows, it times out, exhausts memory, and takes down the database.
Offset pagination (`?page=3&limit=50`) is easy to implement but degrades on large tables and produces duplicates or gaps when records are inserted mid-scroll. Cursor-based pagination solves both problems by anchoring to a stable sort key.
Practical guidance:
- Default to a sensible page size and enforce a hard maximum.
- Return pagination metadata: next cursor, whether more results exist, and total count only if it’s cheap to compute.
- Never silently truncate results without signaling it.
- Make sort order explicit and stable, with a tiebreaker like an ID.
A frequent error is exposing raw database offsets as page numbers in the public contract. Once clients depend on it, you can’t change the internals.
No Rate Limiting or Throttling
An API without rate limits is an API waiting to be accidentally DDoSed by a well-meaning customer running a backfill script. Throttling protects both your infrastructure and other tenants.
The signal for throttling is `429 Too Many Requests`, defined in RFC 6585, ideally paired with a `Retry-After` header so clients know when to come back. Beyond the basics, communicate quota state through response headers so clients can self-regulate before hitting the wall. (Representational state transfer (Wikipedia))
What works: tiered limits by plan, separate limits per endpoint class (reads vs. writes), and burst allowances on top of sustained rates. A common mistake is applying a single global limit that punishes legitimate batch consumers while letting abusive scrapers through because they spread requests across keys.
Leaking Internal Implementation Details
Responses that expose sequential database IDs, internal field names, or ORM artifacts create two problems. First, they leak information useful to attackers, such as record counts and creation order. Second, they couple your public contract to your schema, so a routine refactor becomes a breaking change.
Use opaque identifiers (UUIDs or prefixed IDs) in public responses. Map internal names to stable external names. Never return internal error codes, service names, or version strings that reveal your stack.
This is also where authentication and authorization get conflated. Rolling your own auth is a mistake; the standard frameworks exist for a reason. The OAuth 2.0 Authorization Framework covers delegation, and OpenID Connect layers identity on top. Keep authentication (who are you) strictly separate from authorization (what may you do), and check permissions on every request rather than trusting a token’s claims blindly.
Breaking Changes Without Deprecation
Removing a field, renaming a parameter, or tightening validation without warning is the fastest way to lose developer trust. Deprecation is a process, not an announcement email.
The mechanics are standardized: the `Deprecation` header and the `Sunset` header give clients machine-readable notice. In practice, a healthy deprecation looks like this:
- Announce the change with a date and a migration path.
- Keep the old behavior working for a defined window, typically 6–12 months for public APIs.
- Instrument usage so you know who still calls the deprecated path.
- Contact heavy users directly in addition to the changelog entry.
- Remove only after the window closes and traffic is negligible.
A mistake teams make constantly is deprecating in documentation while leaving runtime behavior unchanged forever. That teaches developers to ignore your deprecation notices.
Missing or Stale API Contracts
If the only description of your API is a wiki page last edited two years ago, developers will reverse-engineer behavior from production traffic. That’s a recipe for fragile integrations.
Publish a machine-readable contract using the OpenAPI Specification. A current OpenAPI document enables generated client SDKs, automated contract tests, and accurate reference docs from a single source. The key discipline is treating the spec as code: version it, review changes to it, and fail the build when implementation and spec diverge.
Practical tips from teams that do this well: generate the spec from code annotations or generate server stubs from the spec, but pick one direction and stick to it. Maintaining both by hand guarantees drift.
Treating Documentation as an Afterthought
Documentation is part of the product. The most common complaints from developers are predictable: no working example requests, no explanation of authentication flow, no error catalog, and no changelog.
What actually helps: a quickstart that gets a developer from zero to a successful call in under five minutes, copy-pasteable examples in at least two languages, a complete error reference, and a changelog with dates. If your API handles sensitive data or user accounts, clear security guidance matters too, the same way readers of a best interest assessors guide expect plain explanations of consequential decisions rather than jargon.
Skipping Observability and Contract Testing
You can’t fix what you can’t see. APIs without request logging, latency histograms, and error-rate tracking fail silently. Add structured logs with correlation IDs, track p50/p95/p99 latency per endpoint, and alert on error-rate spikes rather than raw counts.
Contract testing closes the loop. Run tests that assert response shapes against the published spec on every deploy. When a field type changes unintentionally, the test fails before customers do. This is the same discipline that keeps high-stakes technical workflows reliable, whether you’re debugging a screenshot on a Mac or tracing a failed payment through three services.
Security Mistakes That Keep Recurring
Beyond auth basics, a handful of security errors appear constantly:
- No input validation on nested objects, allowing injection or resource exhaustion.
- Verbose errors in production that reveal whether a username exists.
- API keys in URLs, which end up in logs, browser history, and referrer headers.
- No TLS enforcement or weak cipher configuration.
- Missing authorization checks on nested resources, so a user can read another tenant’s data by changing an ID.
The last one is the most dangerous and the easiest to miss. Test it deliberately: authenticate as one tenant and attempt to access another tenant’s resources on every endpoint.
Conclusion
Most REST API failures aren’t exotic. They’re the predictable result of skipping versioning, improvising error formats, ignoring idempotency, and shipping without limits or observability. The fixes are well documented and, importantly, boring: a stable error schema, explicit status codes, cursor pagination, idempotency keys, tiered rate limits, machine-readable contracts, and a real deprecation process.
The teams that get this right treat the API as a long-lived product with a contract, not a thin wrapper over a database. Start with the two highest-leverage changes: adopt a single error format and publish an OpenAPI document. Everything else gets easier once those exist. And when you’re evaluating tools or third-party services, apply the same scrutiny you’d want applied to your own endpoints, the way a careful reader checks a who owns Pinterest explainer for accuracy before trusting it.
Frequently Asked Questions
What is the most common REST API mistake?
Inconsistent error handling is the most frequently cited problem. When every endpoint returns a different error shape, client code becomes brittle and support costs rise. Standardizing on a single schema, such as the one defined for Problem Details, fixes it once and permanently.
Should I use URI path versioning or header versioning?
For public APIs, URI path versioning (`/v1/`) is usually the better choice because it’s visible in logs, browser tests, and curl commands. Header or media-type versioning suits internal APIs where you control every client and want cleaner URLs. The critical point is choosing a scheme before your first breaking change, not after.
How do I prevent duplicate records when clients retry requests?
Use an `Idempotency-Key` header. The client sends a unique key per logical operation, and the server stores the original response against that key. If the same key arrives again, return the stored response instead of executing the operation a second time. Set a TTL on stored keys, commonly 24 hours.
What status code should an API return for validation errors?
Return `400 Bad Request` for malformed syntax and `422 Unprocessable Content` when the request is well-formed but semantically invalid. Include field-level details in the response body so clients can highlight the exact problem. Avoid returning `200` with an error payload, which breaks monitoring and retry logic.
How long should a deprecated API endpoint stay available?
For public APIs, a window of 6 to 12 months is a common and reasonable norm. During that period, keep the old behavior working, instrument usage to identify remaining callers, and contact heavy users directly. Announce the sunset date in advance and use the standard `Deprecation` and `Sunset` headers so clients can detect it programmatically.
Is offset pagination ever acceptable?
Yes, for small, stable datasets or admin interfaces where total counts matter and data changes slowly. For large or rapidly changing collections, cursor-based pagination is safer because it avoids duplicates and gaps caused by inserts during scrolling. Always enforce a maximum page size regardless of which approach you choose.
