After years of building and auditing APIs, certain mistakes appear with striking regularity. They are not about forgetting syntax, they are architectural choices that seem reasonable at first and become painful at scale. Here are the nine that come up most often in audits, each with the signal that you have it and the fix.

1. Exposing the database schema directly

Returning raw database rows couples every client to your internal schema. Renaming a column or splitting a table then becomes a breaking API change, and internal fields leak into public responses. Put a serialization layer (API Resources, DTOs) between the data and the response, and treat that layer as your published contract.

// Leaks every column, including internal ones
return response()->json($user);

// Controlled, stable contract
class UserResource extends JsonResource {
    public function toArray(Request $request): array {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'created_at' => $this->created_at->toISOString(),
        ];
    }
}

2. Skipping versioning

Shipping an API without a version means every breaking change is a coordinated crisis. Add /v1 to the routes from day one, even for an internal API. It costs nothing up front and lets you run the old and new shapes side by side while consumers migrate on their own schedule.

3. Inconsistent error responses

When each endpoint invents its own error shape, clients cannot handle failures generically and every integration writes bespoke parsing. Adopt one format for the whole API. RFC 9457 problem details is the current standard, served as application/problem+json.

// Each endpoint does its own thing
{ "msg": "not found" }
{ "error_code": 404, "message": "User does not exist" }

// One shape everywhere (RFC 9457)
{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "User with id 42 does not exist.",
  "instance": "/v1/users/42"
}

4. Blocking the request cycle with heavy work

Report generation, email sending, third-party calls, image processing: none of these should block an HTTP response. The request holds a worker, times out under load, and the client has no way to retry safely. Push the work to a queue, return 202 with a job ID, and let the client poll a status endpoint or receive a webhook when it completes.

5. List endpoints without pagination

A list endpoint that returns everything works fine with a hundred rows and takes down the server at a hundred thousand. Always paginate, with a default page size (20 to 50) and a hard maximum (100). Use offset pagination for small stable datasets and admin screens; use cursor pagination for large or fast-changing lists and infinite scroll, so rows are not skipped or repeated when data shifts between requests.

6. No idempotency on writes

A client sends a POST, the network times out, the client retries, and now there are two orders. Accept an Idempotency-Key header, store the first response keyed by that value, and return the stored response for any repeat with the same key. The retry then produces one record, not two.

POST /v1/orders
Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324
Content-Type: application/json

{ "customer_id": 42, "amount": 1990 }

7. No rate limiting on public endpoints

Without rate limiting, one misbehaving client or a scraper degrades the service for everyone, and there is no back pressure against brute-force attempts on auth endpoints. Apply a limiter per API key and per IP, return 429 with a Retry-After header, and set tighter limits on expensive or sensitive routes.

8. Secrets in query parameters

Tokens and API keys in the URL end up in server logs, proxy logs, browser history and Referer headers. Send credentials in the Authorization header, and keep anything sensitive out of the query string and the path.

9. No API documentation

An API without a documented contract forces every consumer to read your source or guess. Generate an OpenAPI description from the code so it cannot drift from the implementation, and publish it. Most frameworks do this with a single package.

Recap

Most of these mistakes are decisions, not accidents, and each one is cheap to get right at the start and expensive to fix later. When you design the first version of an API, walk this list once before you ship it.