Rafael Duarte

I write from integration experience, so my order of concerns starts past the happy path. A response you can parse on the first try teaches you nothing. Pagination comes first because it decides how the whole client is shaped. Offset pagination degrades on large tables and can skip or repeat rows when the underlying data changes mid-scan.

Cursor pagination is stable and has no random access, which means a client cannot jump to page forty and cannot report a total. Both are correct; choosing wrong for the consumer is not. Rate limits need three things to be workable: a limit, a window, and a header saying where you stand. Without the third, a client cannot back off intelligently and ends up retrying into a wall.

Retries need jitter, because a client that reacts to a 429 in synchronised blocks produces a second problem on top of the first. Idempotency matters more than most documentation suggests. A retried POST after a network timeout is the hard case: the server cannot tell a repeat from a new request unless the client sent a key it can recognise. Retrying by default on every error is how a single timeout becomes three charges. Error responses deserve their own standard.

A consistent shape with a machine-readable code, a human-readable message and a field reference is what lets a client react rather than guess. An HTML error page from a reverse proxy tells the client nothing and usually gets parsed as a successful response by anything that only checks the status loosely. Versioning and authentication round it out. A key that never expires is an incident waiting for a schedule, and a version scheme that produces a new path for every release makes deprecation impossible to schedule.