PLAN-101 Career OS
Intermediate 45 Minutes

API Pagination, Error Contracts and Safe Retries

Design a predictable list endpoint, distinguish cursors from offsets and specify what clients should do after a timeout.

Key Learning Objectives

  • Explain offset versus cursor pagination.
  • Return a consistent error object.
  • Recognise retry risks for non-idempotent POST.
  • Test limits and malformed requests.

Choose pagination for a changing dataset

Offset pagination asks for a position in the list and is simple for small stable result sets. When rows are inserted ahead of the offset, clients may see duplicates or skip rows. Cursor pagination uses an ordering key (often created_at plus ID) to ask for items after a known position. It works best when the ordering is stable and the cursor is opaque to clients. Always define a maximum page size on the server.

Make the response contract predictable

A useful list response includes items and nextCursor, with null indicating no subsequent page. Document consistent 400 errors for invalid limit values and 401/403 responses for access errors. Prefer machine-readable error codes alongside a human-readable message. Validation must happen on the server because a client can send requests that do not use your frontend.

{
  "items": [{ "id": "t_10", "title": "Review SQL" }],
  "nextCursor": "opaque-next-page-token"
}

A cursor token encodes a continuation point; a client must treat it as opaque and should not construct its own tokens.

Design retries around idempotency

A network timeout does not tell the client whether a server committed the request. Retrying a POST blindly may create a duplicate. For high-impact creates, idempotency keys can let the server recognize repeated attempts. GET is designed to be safe and idempotent; PUT and DELETE are intended to be idempotent in effect, even if repeated responses differ. Make retry behavior part of the API contract and test it.

Build It: Task feed contract review

Design a task list API with paginated responses, validation and retry guidance.

Project Deliverables

  • Three sample responses including an error.
  • Documented limit bounds and ordering.
  • Test cases for inserted records and duplicate POST.

Acceptance Criteria

  • Limit above maximum returns a clear 400.
  • End of list returns nextCursor null.
  • Repeated create with same idempotency key does not duplicate.

Next Steps & Related Learning

This interactive lesson is part of the API Design curriculum. Continue exploring or try another interactive lesson:

View Full API Design → Arrays, Contiguous Memory & Hash Tables → JavaScript Asynchronous Execution & V8 Event Loop → Relational Database Architecture, B-Trees & Query Optimization → Semantic HTML, Accessible Forms & Document Structure → Python Functions, Dictionaries and Reliable Data Processing → SQL Joins, Missing Rows and Query Correctness → React State, Events and Derived UI → Designing a Task API: HTTP Methods, Errors and Validation → Sliding Window: From Quadratic Loops to a Linear Scan → Responsive CSS Layout: Flexbox, Grid and Fluid Constraints → TypeScript Union Types and Runtime Narrowing → Docker Images, Containers and Reproducible Builds → Git Branches, Pull Requests and Conflict Resolution → Graph Traversal: BFS, DFS and Visited Sets → AWS IAM: Least Privilege and Secure Cloud Access →