Handle errors, pagination, and rate limits

Robust API clients classify errors, bound retries, paginate until a documented stopping signal, and respect rate-limit headers. Retrying everything blindly can amplify an outage.

At a glance

Question	Practical answer
When is it useful?	A client retries a transient 503 with jitter, refreshes credentials for a controlled 401 flow, stops on invalid 400 input, and follows next-page cursors until none remains.
What should you do?	Write a client against a mocked API that returns two pages, one transient failure, and a rate-limit response; log each decision without logging secrets.
How do you know it worked?	Every item appears once, retry count stays within the limit, invalid requests fail fast, and the client waits until the documented reset time.
Common failure	Avoid offset assumptions when the API uses cursors, and never retry non-idempotent writes without an idempotency strategy.

flowchart LR
  A[Question] --> B[Handle errors, pagination, and rate limits]
  B --> C[Small example]
  C --> D[Evidence]

The important idea is not to stop at a definition: connect the concept to a small example and observable evidence.

Worked example

A client retries a transient 503 with jitter, refreshes credentials for a controlled 401 flow, stops on invalid 400 input, and follows next-page cursors until none remains.

Before acting, write the success signal. Change one condition at a time, observe the result, and record assumptions. For Handle errors, pagination, and rate limits, this separates what you know from what you are merely guessing.

Practice in 20–30 minutes

Goal: Write a client against a mocked API that returns two pages, one transient failure, and a rate-limit response; log each decision without logging secrets.

1. Record the starting state and your prediction.
2. Implement the smallest version without adding unnecessary tools.
3. Change exactly one input or constraint and repeat.
4. Save a command, screenshot, output, or checklist as evidence.

Expected result: Every item appears once, retry count stays within the limit, invalid requests fail fast, and the client waits until the documented reset time.

What can go wrong

Avoid offset assumptions when the API uses cursors, and never retry non-idempotent writes without an idempotency strategy.

When the result differs from your prediction, do not change many things at once. Check inputs, versions, environment, permissions, and logs, then repeat from the smallest example.

Definition of done

• I can explain the concept in my own words.
• I completed the small example and kept evidence.
• I know one failure mode and how to check it.
• Someone else can repeat the work without guessing missing steps.

Go deeper

Use the linked resource or repository at the end of the page when you need a full implementation. Check current versions before applying commands to a real project.