Skip to content
APIHiver

REST API Design Mistakes: 12 Tested With Real Numbers

12 REST API design mistakes, each reproduced on a small test server: what broke, the measured numbers, and the fix. Rate limits, retries, paging, IDs and more.

9 min readBy Mivaan Sanghani
In this post
  1. How we tested
  2. The 12 mistakes at a glance
  3. 1. A fixed-window rate limiter lets through double the limit
  4. 2. A retry with no idempotency key charges the customer again
  5. 3. A 429 without Retry-After makes clients hammer you
  6. 4. Returning HTTP 200 with an error inside hides your failures
  7. 5. A 403 tells a stranger that the object exists
  8. 6. Offset pagination slows down the deeper you go
  9. 7. A cursor on a timestamp alone skips rows
  10. 8. Returning every field of every row is slow and costly
  11. 9. Big numeric IDs change when JavaScript reads them
  12. 10. A date with no timezone means different times on different machines
  13. 11. Renaming a field in place breaks every client
  14. 12. Sending the same big response again and again
  15. A bonus mistake: PUT that behaves like PATCH
  16. Which to fix first
  17. What we did not test
  18. Quick checklist
  19. Related reading

Most API design advice is a list of rules. This one is a list of mistakes we reproduced: we built a small server for each one, ran it, and wrote down what broke.

Our API design principles guide covers the rules in 12 short sections. This post is the other half: what happens in numbers when you skip one. Every number below comes from a test we ran on 18 November 2026 on a laptop, with the code kept small enough to read.

Six before and after cards from our API tests: a rate limit burst of 200 versus 100, a retried payment creating 3 charges versus 1, 8,874 requests versus 14, a deep page taking 11.6 ms versus 0.02 ms, a 518,671 byte list versus 521 bytes, and 8,491 bytes versus 0 on a repeat request

How we tested#

Each test is a short Node.js or Python script with an in-memory server or a local database. They are small on purpose, so they show one behaviour clearly. They are not benchmarks of your production system, and your numbers will differ. What carries over is the shape of the failure.

Where a standard defines the right behaviour, we link to it: RFC 9110 for HTTP methods and status codes, RFC 6585 for 429, and RFC 9457 for error bodies.

The 12 mistakes at a glance#

#MistakeWhat we measuredFix
1Fixed-window rate limit200 requests let through in 0.2 s, limit was 100Sliding window or token bucket
2Retry with no idempotency key3 charges for 1 orderIdempotency key
3No Retry-After on 4298,874 requests vs 14Send Retry-After
4HTTP 200 for errors0% error rate on the dashboard, 5% realReal status codes
5403 for other people's objectsCaller can tell real from missing404 plus an ownership check
6Offset pagination11.64 ms vs 0.02 msKeyset cursor
7Cursor on a timestamp only119 of the first 200 rows skippedAdd the ID as a tie-breaker
8Returning every field of every row518,671 B vs 521 BLimits and field selection
9Big IDs as JSON numbers1234567890123456789 became 1234567890123456800IDs as strings
10Dates with no timezone04:30 UTC vs 18:00 UTCAlways send an offset or Z
11Renaming a field in placecharge user undefinedAdd the new field, keep the old one
12No ETag on big responses8,491 B on every repeat vs 0 BETag and 304

1. A fixed-window rate limiter lets through double the limit#

A fixed window counts requests in clock-aligned minutes. A client can send 100 requests at the end of one minute and 100 more at the start of the next. We set a limit of 100 a minute and sent a burst across the boundary:

fixed   allowed in 0.2s straddling the boundary: 200 (first burst 100)
sliding allowed in 0.2s straddling the boundary: 100 (first burst 100)
bucket  allowed in 0.2s straddling the boundary: 100 (first burst 100)

Fix: use a sliding window or a token bucket. Both held the limit at 100.

2. A retry with no idempotency key charges the customer again#

A client sends a payment and the connection times out. The client cannot know whether the server saw it, so it retries. With no key, the server treats each try as new:

no key:   charges created = 3
with key: charges created = 1

Fix: accept an idempotency key, store the first result under it, and return that result on repeats. Stripe's documentation describes this pattern and says its keys can be removed after at least 24 hours.

3. A 429 without Retry-After makes clients hammer you#

A server allowed 5 requests a second and a client needed 12 calls. We tried three client behaviours against it:

naive        server saw 8874 requests, 8862 were 429s
sleep 50ms   server saw 52 requests, 40 were 429s
Retry-After  server saw 14 requests, 2 were 429s

The naive count changes from run to run, but it is always in the thousands. Fix: return the 429 status from RFC 6585 together with a Retry-After header, and say in your docs that clients should honour it.

4. Returning HTTP 200 with an error inside hides your failures#

We served 1,000 requests where 50 failed. With real status codes, the usual dashboard that counts 5xx responses showed a 5% error rate. When the same failures came back as 200 with {"error": ...} in the body, it showed 0%.

proper status codes -> dashboard 5xx rate: 5%
always-200 style    -> dashboard 5xx rate: 0%  (real failures: 50/1000)

Fix: use the status code that matches the outcome, and put details in a standard body such as RFC 9457 problem details.

5. A 403 tells a stranger that the object exists#

We built three versions of GET /orders/{id}, logged in as Alice. Order 1 is hers, order 2 is Bob's, order 999 does not exist.

vulnerable: Bob's order 2 -> 200 {"id":2,"owner":"bob","total":99}
design A:   Bob's order 2 -> 403, missing 999 -> 404   (Alice can tell them apart)
design B:   Bob's order 2 -> 404, missing 999 -> 404   (no difference)

The first version is the real bug: no ownership check at all, which OWASP lists as Broken Object Level Authorization, the first item in its 2023 API Top 10. Design A fixes that but lets Alice count other customers' orders by trying IDs. Fix: check ownership on every request, and return 404 for both cases when the existence of the object is itself private.

6. Offset pagination slows down the deeper you go#

We filled a table with 500,000 rows and asked for 20 rows at a time, sorted by date:

offset page 1      0.02 ms
offset page 20000  11.64 ms
keyset deep page   0.02 ms

The database still has to walk past every skipped row. A keyset query ("rows after this one") goes straight to the spot through the index. Fix: return a next cursor built from the last row's sort key.

7. A cursor on a timestamp alone skips rows#

In the same table, 50 rows share each timestamp. We paged by "created after the last timestamp I saw":

created-only cursor: got 200 rows, only 81 of the first 200 seen

The next page started after the whole timestamp, so up to 50 rows were skipped each time. In this test, 119 of the first 200 rows never appeared. Fix: sort by the timestamp and the ID, and put both in the cursor. Our keyset query used (created, id) > (?, ?).

8. Returning every field of every row is slow and costly#

A list endpoint of 1,000 users returned everything by default:

all 1000 users, all fields : 518671 bytes
first 20 users, all fields :  10291 bytes
first 20, fields=id,name    :    521 bytes

Two separate fixes stack: a default page size (a 98% cut here) and field selection on top (a further 95%). Separately, compression helps: a 24,957-byte JSON response (compact) came to 3,549 bytes with gzip level 6, about 14% of the size. Gzip level 9 saved only 97 bytes more and took more than twice the CPU time.

9. Big numeric IDs change when JavaScript reads them#

server sends id      : 1234567890123456789
JS JSON.parse reads  : 1234567890123456800
two different ids collide? true
as string it survives: true

JavaScript numbers are exact only up to 9,007,199,254,740,991, as MDN documents. Past that, two different IDs can turn into the same number. Fix: send IDs as strings, even when they look numeric.

10. A date with no timezone means different times on different machines#

We parsed the same strings on a machine set to India time (UTC+5:30):

2026-11-17T10:00:00Z         -> 2026-11-17T10:00:00.000Z
2026-11-17T10:00:00+05:30    -> 2026-11-17T04:30:00.000Z
2026-11-17T10:00:00          -> 2026-11-17T04:30:00.000Z
2026-11-17                   -> 2026-11-17T00:00:00.000Z

The third string has no zone, so it was read as local time: 04:30 UTC on this machine, but 18:00 UTC on a machine set to Los Angeles time. Fix: always send an offset or Z, and say in your docs that timestamps are UTC.

11. Renaming a field in place breaks every client#

A client read userId from the response. After the server renamed it to customerId:

v1                             -> charge user 7
rename userId->customerId      -> charge user undefined
additive (keep old, add new)   -> charge user 7

Nothing errored. The client simply charged a user called undefined. Fix: treat additions as safe and renames and removals as breaking. Add the new field, keep the old one, and remove it only in a new version with notice.

12. Sending the same big response again and again#

The first request returned 8,491 bytes. With an ETag, the repeat request returned a 304 Not Modified with no body:

first request : 200 body bytes 8491
repeat w/ ETag: 304 body bytes 0

RFC 9110 defines the conditional request flow behind this. Fix: send an ETag on large, stable responses and honour If-None-Match.

A bonus mistake: PUT that behaves like PATCH#

A user had an id, name, email and phone. We changed only the email:

PUT   {email} -> {"id":1,"email":"[email protected]"}
PATCH {email} -> {"id":1,"name":"Asha","email":"[email protected]","phone":"555"}

RFC 9110 describes PUT as creating or replacing the state of the target resource, so the fields we left out were gone. If your clients send partial updates, document PATCH for that, and make sure PUT does not silently half-work.

Which to fix first#

  1. Anything that leaks data or loses money: #5 (ownership checks) and #2 (idempotency keys).
  2. Anything that hides problems: #4 (honest status codes) and #3 (Retry-After).
  3. Anything that corrupts data quietly: #7 (cursors), #9 (big IDs) and #10 (dates).
  4. Anything that grows with traffic: #6 (offset paging), #8 (list size) and #12 (caching).
  5. Anything that breaks customers on release day: #11 (renames).

What we did not test#

  • We ran each test on a laptop with small scripts. We did not run a load test or measure a production system.
  • The pagination timings use SQLite with 500,000 rows. A different database will give different numbers, but the same shape.
  • The rate-limit tests use a simulated clock, not live traffic.
  • We did not test CORS, webhook signature checks, or authentication flows in this post.

Quick checklist#

  • Every object read checks that the caller owns it
  • Payments and other writes accept an idempotency key
  • Errors use real status codes and a standard error body
  • 429 responses include Retry-After
  • Lists are paginated with a keyset cursor that includes an ID
  • IDs are strings and timestamps carry a timezone
  • Renames are done by adding a field, not changing one
  • Large stable responses send an ETag

Try APIs on the APIHiver marketplace

Discover free and paid APIs for travel, finance, AI, weather, maps and more. Test each endpoint in your browser and use one key for all of them.

Share this post

Frequently asked questions

What are the most common REST API design mistakes?
The ones we measured as most costly: returning HTTP 200 for errors so monitoring sees nothing, offset pagination on large tables, retries without an idempotency key that charge a customer twice, ignoring Retry-After on 429 responses, and big numeric IDs that JavaScript changes when it parses the JSON.
Should an API return 403 or 404 for someone else's object?
If you do not want a stranger to learn that the object exists, return 404 for both missing objects and objects the caller may not see. In our test, 403 let a logged-in user tell a real order from a missing one. The real fix is still an ownership check on every request, which 404 does not replace.
Why is offset pagination slow?
The database still has to walk past every skipped row. On a 500,000-row test table, page 1 took 0.02 ms and a page 20,000 deep took 11.64 ms, while a keyset query asking for the same deep page took 0.02 ms.
Why did my 19-digit ID change in JavaScript?
JavaScript numbers are precise only up to 9,007,199,254,740,991. A larger integer sent as a JSON number is rounded when parsed. In our test 1234567890123456789 was read as 1234567890123456800. Send big IDs as strings.
What is the difference between PUT and PATCH?
PUT replaces the whole resource with what you send, so fields you leave out are removed. PATCH changes only the fields you send. In our test a PUT with just an email left the user with no name and no phone number, while the same change with PATCH kept them.
How do I make a payment API safe to retry?
Make the client send an idempotency key with each charge and have the server return the stored result when it sees the key again. Without a key, three retries of one timed-out request created three charges in our test. With a key, one.
Do I need to add all twelve fixes at once?
No. Start with the ones that can lose money or leak data: ownership checks, idempotency keys and honest status codes. Pagination, field selection and caching headers can follow as your traffic grows.
Developer Tools

API-First Development: A Practical Guide (2026)

What API-first development is, how it differs from code-first, the 6-step workflow with an OpenAPI example, Spectral linting, Prism mocking and its limits.

10 min read