APIs in Production: Versioning, Rate Limiting, Pagination, Errors

Once an API is used in production, a handful of operational concerns decide whether integrations stay stable. The following points are industry-standard and covered by HTTP standards (IETF/RFC) as well as MDN.

Versioning. APIs change, but existing clients shouldn't suddenly break. It's common to put a version in the path, e.g. /v1/. New, non-backward-compatible changes then land in /v2/, while /v1/ keeps running for a transition period. That way, customers can migrate at their own pace.

Rate limiting. To avoid overload and abuse, the server limits how many requests a client may make within a time window. If the limit is exceeded, the server responds with the status code 429 Too Many Requests. The response should explain what happened and can include a Retry-After header indicating how long the client should wait before trying again. Retry-After accepts either a number of seconds or an HTTP date.

Pagination. Large lists aren't delivered in a single response, but split into pages. Two approaches are common:

• Offset/limit (e.g. ?limit=50&offset=100): simple, but prone to shifting when the underlying data changes.
• Cursor-based (e.g. ?limit=50&cursor=...): the server returns a pointer to the next page, stable even with large numbers of entries.

Consistent error formats. Errors should be machine-readable and structured the same way across all endpoints, typically as JSON with fields like an error code, a message, and optional details. This matches the standards' recommendation that the response should explain the cause. Choosing the correct status code matters (e.g. 400 for malformed input, 401/403 for auth, 404 for not found, 429 for rate limiting, 5xx for server errors).

Idempotency for retries. A method is idempotent if multiple identical requests have the same effect on the server as a single one. Per RFC 9110, GET, HEAD, PUT, and DELETE are idempotent. This matters for safe retries: if the connection drops before the client could read the response, it can safely resend an idempotent request. POST is not idempotent; to make it safely retryable anyway, many APIs use an idempotency key, so the server can detect duplicate requests and avoid executing them twice.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 3600

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 3600
  }
}

Example of a 429 response with a Retry-After header and a consistent JSON error format

Sources

• 429 Too Many Requests MDN Web Docs
• Retry-After header MDN Web Docs
• RFC 6585: Additional HTTP Status Codes (Section 4, 429 Too Many Requests) IETF / RFC Editor
• RFC 9110: HTTP Semantics (9.2.2 Idempotent Methods, 10.2.3 Retry-After) IETF / RFC Editor