Lesson 7 of 10

API Debugging in the Field

"The API just stopped working" is never the actual bug. Turning that sentence into a reproducible request is the entire job.

The bug report is never the bug

A customer describes an outcome, not a request. Your first job is translating one into the other.

"It just stopped working" could mean a 401, a 429, a 500, or a client-side bug that never reaches your API at all. Before you touch a debugger, get as close as you can to the actual request— method, path, headers, body — that the customer's system sent. Everything downstream depends on starting from something concrete instead of a paraphrase.

Building a repro in Postman

Four features turn a one-off request into something reusable and shareable.

Environments

Swap keys and hosts between sandbox and production without rewriting a single request.

Collections

Group related requests into something shareable — engineering can rerun the exact same calls, not a paraphrase of them.

Pre-request scripts

Compute a signature, timestamp, or auth header automatically before the request goes out.

Tests (assertions)

Assert the response matches what you expect, so rerunning the same request later catches a regression instead of requiring a manual re-read.

Exercises

Look at the sanitized request/response below, then work through both exercises.

POST /v1/messages HTTP/1.1
Authorization: Bearer <redacted>
Idempotency-Key: 8f14e45f-ceea-467e-bd42-4a6f3d1e9c21

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1717000000

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 30 seconds."
  }
}

Concept check

Answer in your head first, then click a question to reveal the answer.

Scenario checklist

Work through the sample request/response and check each item off. Progress is saved in your browser.

Reconstruct the actual request being sent (method, path, headers, body)Reproduce it in Postman against the same environment the customer usedRead the full response, not just the status codeIdentify whether this is rate limiting, an auth issue, or an application errorDescribe the fix or the guidance you would give the customer

Go deeper

These primers are a starting point. Read the primary sources to build real fluency.

Postman Docs: Building requestsThe mechanics of assembling and sending a request from scratch Postman Docs: Managing environmentsKeeping sandbox and production requests interchangeable Stripe Docs: Idempotent requestsThe clearest widely-cited explanation of why idempotency keys matter on retry MDN: 429 Too Many RequestsWhat the status code means and which headers accompany it

Training Notes

What building this project taught me.

This builds on HTTP, not repeats it

HTTP covers the protocol vocabulary — methods, status codes, headers. This lesson is the workflow for using that vocabulary to reproduce a live customer-reported bug, with Postman as the tool.

Rate-limit header names vary by provider

X-RateLimit-* here is illustrative — some APIs use different header names or a Retry-After-only pattern. Confirm the actual headers in the docs for whichever API you're debugging.