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 but become painful at scale.

1. Exposing the database schema directly

Returning raw database rows from your API couples your clients to your internal schema. Any migration,renaming a column, splitting a table,becomes a breaking API change. Always use a serialization layer (API Resources, DTOs) between your data and your response.

2. No versioning

Shipping a public or semi-public API without versioning means every breaking change is a crisis. Add `/v1/` to your routes from day one. It costs almost nothing, and saves enormous pain when you need to evolve the contract.

3. Inconsistent error responses

// Bad: each endpoint has its own error format
{ "msg": "not found" }
{ "error_code": 404, "message": "User does not exist" }
{ "errors": ["Resource not found"] }

// Good: consistent RFC 7807 format
{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "User with id 42 does not exist."
}

4. Blocking the request cycle with heavy tasks

Report generation, email sending, PDF creation,these should never block an HTTP response. Push them to a queue, return a job ID immediately, and let the client poll or receive a webhook when the task completes.

5. No pagination on list endpoints

• ✓Missing idempotency on POST endpoints (duplicate requests = duplicate data)
• ✓No rate limiting on public endpoints (DoS vulnerability)
• ✓Secrets in query parameters instead of headers (logs expose them)
• ✓No API documentation,OpenAPI/Swagger takes minutes to set up