How to troubleshoot an API request when you work in support

This is for people who help customers, not people who are building an integration. You do not need to become an API developer. After this page you should be able to ask for the right evidence, read one failing call, and write a clear update.

Product in the story: Northstar Billing. Customer: Harbor Analytics. Their nightly job pulls open invoices from Northstar’s API into their own finance tool. You are customer-facing support. Sam is the person on the ticket.

Words you will see

• API. A doorway other software uses to talk to the product. Harbor’s nightly job talks to Northstar this way. A human in the UI is a different path.
• Request / response. The request is what Harbor sent. The response is what Northstar sent back.
• Status code. A short number on the response. 401 means “I do not accept who you are.” We will contrast 403 and 429 later. You do not need the whole list today.
• API key / token. The secret that proves who is calling. You never ask them to paste the full value into chat, Slack, or the ticket.
• Request id. A receipt number for that one call, here req_9c2a. You can search logs with it. It is not the password.

The ticket

From: Sam, Harbor Analytics
Subject: Sync broken: invoices not arriving

Our nightly invoice sync failed. Finance will not close until this works. It was fine Friday.
Error in our logs: "Northstar 401". We rotated keys last week like your email told us to.

What you know: month-end is blocked, it broke after a key rotation, they saw a 401. What you do not have yet: the actual call. “401” in a sentence is a clue, not evidence. Your next move is to write back and ask for the request. Do not assume rotation is the root cause just because it sounds technical.

Write back and ask for evidence

This is the support move most API tutorials skip. You cannot see Harbor’s laptop. You ask them to send a copy of the failing call, with secrets removed.

Hi Sam, sorry finance is blocked on this.

A 401 means Northstar did not accept the credentials on that call. To see which call, I need one example of what you are sending.

Easiest if you already use Postman:
• the method and URL
• the status code and response body
• headers, with Authorization deleted or replaced with [REDACTED]
• a timestamp and any request id in the response

If this is failing in a browser instead, you can export a HAR from the Network tab. Remove cookies and Authorization first. A full HAR often includes session cookies. Do not paste a live API key into this thread.

Once I have that, I can compare it with what we see on our side.

Postman is a window for sending HTTP requests without writing code. Lots of customers already have the call saved there. A HAR file is a download of what the browser sent and received. Prefer the Postman export when they are calling an API from a job or from Postman. Use a HAR only when the failure is in a web page, and only after they sanitise it.

One example of the failing call

We freeze one example of the failing call so we can walk through the same evidence. Harbor sent this back (secrets already removed).

GET https://api.northstar-billing.example/v1/invoices?status=open&limit=50
Authorization: Bearer [REDACTED]
X-Request-Id: req_9c2a
Accept: application/json

HTTP/2 401
X-Request-Id: req_9c2a
WWW-Authenticate: Bearer realm="northstar"
{
  "error": "unauthorized",
  "code": "auth_token_invalid",
  "message": "The access token is missing, expired, or revoked."
}

GET …/v1/invoices: The URL they called. GET means they asked to read data, not to change it. status=open&limit=50 is the filter.

Authorization: Bearer [REDACTED]: Where the secret sat. In your notes you write [REDACTED] only. You never store the real value.

X-Request-Id: req_9c2a: The receipt. Same id on the request and the response, so you can search for this one call.

HTTP/2 401: Northstar answered “I do not accept who you are.” That is different from 403 (I know who you are, you are not allowed) and 429 (too many calls, slow down).

code: "auth_token_invalid": The machine reason. Missing, expired, or revoked. It does not mean “the invoices API is down.”

Tools on your side

• Postman (inspect, don’t steal their key). You might look at what they sent, or try the same URL against a company sandbox with a scoped support token. You do not paste Harbor’s live secret into your own Postman.
• Browser Network tab. Useful if the failure is in a web app. That is the live Tier 1 DevTools skill.
• Admin credential list and request-id search. Your side: which keys exist, which are revoked, whether req_9c2a shows up in logs.

Then investigate each check

1. URL host. Is this api.northstar-billing.example (production) or a sandbox host? Docs get copied. A valid sandbox key on the production URL still 401s. That is why you confirm the host before you theorise about outages.
2. 401 vs 403 vs 429. 401 = credentials not accepted. 403 = accepted, but this user or key cannot do this action. 429 = rate limit. Sam’s body says auth_token_invalid, so you stay on credentials, not permissions, and not “the API is melting.”
3. Credential list in admin. Harbor’s workspace shows key sk_live_…8841 as Revoked 14 Aug 18:02 UTC (after the rotation email) and sk_live_…19aa as Active. You still do not display the secret. Prefixes are enough to ask “which one are you sending?”
4. Ask which prefix they are sending. First characters only, if your product shows prefixes. They are still sending sk_live_…8841, the revoked one. That is evidence, not a guess.
5. Do not start with signatures. Some APIs sign the body (HMAC). This call is a GET with no body, and the server already said the token is invalid. Signature debugging would be the wrong rabbit hole.

A hypothesis you can test

Working idea: Harbor’s nightly job still uses the revoked key. The rotation email created a new key; the job was not updated.

You would drop that idea if: they send the active prefix and still get 401; the error becomes 403 on one invoice endpoint (permissions, not a dead token); or other Harbor keys work from the same place (then the job config is the question, not “Northstar is down”).

A green status page plus one customer 401 is usually credentials or environment. It is not proof of an API outage.

What to keep in the ticket

• Method, path, query, timestamp, and request id (req_9c2a).
• Status code and machine error code (auth_token_invalid).
• Key prefix and status from admin (revoked or active). Never include the secret.
• Production host or sandbox host.
• Customer impact in one sentence (finance cannot close).

Customer update

Hi Sam, the request id req_9c2a is a 401 with auth_token_invalid. In your workspace the key that matches the prefix you are sending was revoked on 14 August when the new key was created. The new key is marked active.

I cannot see or resend the secret (that is by design). Please update the nightly job to the new key in your secret store, then retry. If you still get a 401, send a new request id and confirm you are calling the production host, not sandbox.

I am not treating this as an API outage. If the new key fails the same way after you have updated the job, I will take that to engineering with the evidence above.

When to escalate

Do not escalate yet

A mismatched key after a documented rotation is a configuration outcome. Engineering does not need a Sev-1 because finance is anxious.

Escalate if

The active key, the correct host, and a redacted 401 still reproduce from Harbor and from a company sandbox with a scoped test token; or many customers 401 at once; or the error code and HTTP status disagree in a way the docs do not describe. Then file with request ids, timestamps, and redacted headers. Never include a live bearer token.

In this story, Harbor updates the job. The next nightly run returns 200. You close with the successful request id. You do not add a secret to the thread “for next time.”