It’s Monday morning, and the first thing you see when you open Slack is a Zapier error alert. The log shows a three-digit number you’re not familiar with — 403, or 502, or 429 — and if you don’t know what you’re looking at, it’s tempting to just ping engineering.
That is expensive. Most of those codes will tell you what the problem is and whose problem it is: yours, your team’s, or the vendor’s. Once you can read them as triage signals rather than random numbers, some solutions will come much faster.
TL;DR
- HTTP errors mostly sort into two buckets: 4xx usually means something on your side is wrong; 5xx usually means something on their side is wrong. Usually, not always.
- 401 / 403 are usually access problems on your side — bad or missing credentials vs insufficient permission. 429 is a rate limit (usually yours). 500 / 502 / 503 / 504 are usually the vendor’s.
- The sneakiest failure is 200 OK with wrong data — success on paper, garbage in practice.
- Before you escalate a 5xx, check the vendor’s status page. An active incident often means you can wait instead of burning engineering time.
Two buckets: 4xx and 5xx
HTTP status codes group by hundreds. For day-to-day ops, you mostly care about two ranges:
- 4xx (client error): the server thinks your request is the problem — config, credentials, permissions, shape of the data, how often you’re calling, wrong URL.
- 5xx (server error): the server thinks it failed — overload, a broken upstream hop, something unexpected on their box. (Usually nothing you can do about it.)
That’s the first-pass ownership map, and it can help route most tickets correctly.
But it isn’t a law. A vendor bug can slap a 400 on a request that’s actually fine. A 401 can show up because they rotated keys and forgot to tell you. A fragile app can turn your malformed payload into a 500 instead of a clean 400. I’ll name those exceptions below — the heuristic survives; the overstatement doesn’t.
(More on the split in RFC 9110 §15 and the MDN status-code index.)
The triage table
Plain English, usual owner, first move. Scan this when the Slack ping lands.
| Code | Plain English | Usually owned by | First move |
|---|---|---|---|
| 400 Bad Request | “We don’t understand what you sent” | You / your dev team | Check the integration config — the payload or framing looks wrong to them |
| 401 Unauthorized | “We don’t recognize your credentials” | You | Confirm the key/token is correct, active, and not expired or revoked |
| 403 Forbidden | “We understood the request, but you’re not allowed to do this” | You / IT (sometimes their firewall) | Check scopes, roles, plan features, or allowlists; read the error message too, since some vendors use 403 for a bad key or a quota limit |
| 404 Not Found | “That address or resource doesn’t exist” | Check both | Wrong URL, deleted object, or (sometimes) their routing |
| 429 Too Many Requests | “You’ve sent too many requests in this window” | You (usually) | Slow down or stagger; if a Retry-After header is present, respect it; talk limits / tier at renewal if it keeps happening |
| 500 Internal Server Error | “Something broke on our end” | Vendor (usually) | Check their status page; file a ticket if it persists |
| 502 Bad Gateway | “A gateway in the middle got a bad/invalid response from the next service” | Vendor (usually) | Status page; often transient — a proxy, VPN, or firewall on your own network can own this too |
| 503 Service Unavailable | “Temporarily can’t handle this (overload or maintenance)” | Vendor (usually) | Status page; wait and retry (they may send Retry-After) |
| 504 Gateway Timeout | “A gateway in the middle gave up waiting for the next service” | Vendor (usually) | Status page; before replaying a step that creates something, check it didn’t already go through |
Treat “usually” as load-bearing. The next section is why.
Where the heuristic breaks
This is not gospel, because:
- 4xx isn’t always your fault. Servers return 400 for what they perceive as a client error, including if their own validation is buggy. A 401 can mean they revoked or rotated credentials on their end. A 404 can be their routing breaking. (It can also be a real resource hidden behind “not found” because you lack permission, which puts it back on your side.)
- 5xx isn’t always theirs. A malformed request can tip a fragile server into a 500. A misconfigured gateway on your stack (a corporate proxy, VPN, or internal gateway) can surface a 502 because your hop got a bad upstream response and the ownership sits closer to you than to the SaaS origin.
- 429 is usually your usage, but shared keys, shared IPs, or org-wide quotas mean another team or integration can contribute to the same limit.
None of that changes what the codes mean. It labels real-world misrouting so you don’t treat the ownership column like a court verdict.
The sneaky 200
A 200 OK means the HTTP request succeeded. It does not mean the business data is correct.
That can do real damage in CS and RevOps, because many tools only alert on non-2xx. Nobody’s Slack channel lights up. Syncs “succeed.” Dashboards look green. But something isn’t right.
How you catch it: spot-checks against a source of truth, reconciliation jobs, and the same skepticism you’d bring to a report that “ran fine” but the numbers seem wrong.
Some APIs even report outright failures inside a 200, with the error in the body.
If your mental model is “error codes = problems, 200 = fine,” adjust it: the status tells you the HTTP request succeeded, not that the payload is trustworthy.
Check the status page first
Before you escalate a 5xx to engineering, open the vendor’s status page.
Examples: status.stripe.com, status.hubspot.com. Many SaaS vendors publish one — try status. + their name, or search ‘[vendor] status’.
If there’s an active incident, your ticket may be duplicate noise. Waiting (or posting a calm “vendor outage, monitoring” note) often beats waking someone who already knows. But remember that incidents can be regional, partial, or not yet posted.
Five fields for a useful escalation
When you do escalate, you can save time if you send five things:
- Error code (and the exact message text if you have it)
- Tool / integration (Zapier zap name, middleware, which API)
- Action that failed (be specific: create contact, sync deal, pull invoice)
- Timestamp (with timezone)
- Frequency (once, every run since Tuesday, intermittent?)
That’s it. Code + tool + action + timestamp + frequency. Engineering can reproduce or rule out without a scavenger hunt through Slack threads.
Persistent 429s can be a renewal conversation
A one-off 429 means “back off.” Per RFC 6585 §4 (and MDN’s 429 page), the response may include a Retry-After header — optional, not guaranteed. If it’s there, use it. If it isn’t, slow down and stagger anyway.
But a 429 that keeps coming back every busy Monday could be a budgeting signal: your plan’s rate limit doesn’t match how the business actually uses the API. That conversation belongs with whoever owns the vendor relationship and the renewal.
Slow down first. Respect Retry-After when present. Then, if the pattern is structural, take it to the commercial table.
Wait or act now
Same three digits, different urgency:
- A 503 during a posted maintenance window? Expected. Wait, retry, don’t page people.
- A 502 that flickered once and cleared? Often transient at a gateway hop. You should watch it, but don’t treat one blip like a fire.
- A 401 on a key that worked last week and broke this week? Act now because something probably changed.
- A 403 that started after someone “tightened security”? Permissions or scopes moved. That’s an IT / admin fix.
- A 429 during a known batch job? Throttle the job. A 429 that appeared after you launched three new automations on the same key? Usage math changed; see the renewal conversation above.
One caution before you hit replay: if the failed step creates something (a contact, a deal, an invoice), a 5xx or a timeout doesn’t prove it didn’t go through. Check the vendor side for a duplicate first, and space retries out instead of replaying everything at once.
You don’t need to become a developer to stop treating every API error as an engineering page. You need a triage map, a status-page reflex, five fields in the report, and the humility to say “usually” out loud.
FAQ
What does a 429 error mean?
You’ve hit the API’s rate limit for a time window. Slow down or stagger requests; if Retry-After is present, wait that long. If 429s keep showing up under normal load, your plan may not match your usage — take that to renewal, not just to engineering.
What’s the difference between a 4xx and a 5xx error?
4xx usually means something on your side looks wrong to the server (request, credentials, permissions, config). 5xx usually means the vendor’s system failed (or a gateway in the path did). Both have exceptions — treat the split as first-pass triage, not proof of fault.
What does 500 Internal Server Error mean?
Something unexpected broke on the server’s end. Check their status page before you escalate internally; file a ticket if it persists past the incident or keeps repeating with no public notice.
Can an API return success but still be wrong?
Yes. A 200 means the request succeeded at the HTTP layer. The body can still be missing fields, stale, or business-wrong — and tools that only alert on errors won’t tell you.
401 vs 403 — aren’t those both “key problems”?
Not quite. 401 is authentication: they don’t accept your credentials (missing, wrong, expired, revoked). 403 is authorization: they understood the request but won’t let you do it (scopes, roles, plan, allowlist, sometimes their firewall). Both are usually access problems on your side; the fix is different. (Some vendors also use 403 for a bad key or a quota limit, so read the error message.)
What about 502 vs “the service is down”?
502 means a gateway or proxy got an invalid response from the next service upstream. 504 is the timeout version: the gateway gave up waiting for a reply. 503 is the temporary overload-or-maintenance code. Check status, then decide wait-vs-act.
Leave a Reply