DEV Community: yuanke215

401 vs 403 vs 404: The Status Code Mistakes That Break APIs

yuanke215 — Sun, 27 Sep 2026 03:11:16 +0000

Originally published at ipcalcplus.com.

Every API review I've ever done contains at least one of these bugs: a login failure that returns 500, a rate limit that returns 400, a "resource not found" that returns 403 for security reasons and confuses every client developer for the next two years.

Status codes are the API's contract with its clients. Break the contract and your consumers write defensive code around your bugs — code that then breaks when you fix the bug. This is a guide to the codes that actually matter, the distinctions people get wrong, and the two codes almost nobody uses correctly.

The two-second mental model

First digit = who broke it:

2xx — it worked
3xx — go somewhere else
4xx — the client broke it
5xx — the server broke it
1xx — hold on, I'm not done (mostly invisible; the one you'll see is 101 during a WebSocket upgrade)

That's the whole taxonomy. Everything interesting is in the distinctions within 4xx and 3xx.

401 vs 403: the distinction clients depend on

The most misused pair in REST.

401 Unauthorized actually means unauthenticated. The server does not know who you are. The client's correct response: acquire credentials (log in, refresh the token, add the API key) and retry.

403 Forbidden means authenticated but not allowed. The server knows exactly who you are and is declining to serve you. The client's correct response: give up. Retrying with the same credentials will produce the same answer.

When you return 403 for missing credentials, clients can't tell "I need to log in" from "I'm not permitted," and their retry logic breaks. The memorable version:

401 = "who are you?"
403 = "I know who you are, and no."

One deliberate exception: many APIs return 404 for resources the caller isn't allowed to know exist — a private repo is "not found" rather than "forbidden," so the API doesn't leak which IDs are valid. That's a legitimate design choice; document it, because it's the opposite of what clients expect.

404 vs 410, and the SEO angle nobody mentions

404 Not Found is the most famous code and the most expensive one to misuse on the web. The nuance: 410 Gone means "this used to exist and was deliberately removed." Search engines treat 410 as a stronger signal than 404 — a 404 page may come back, a 410 page won't, so it gets deindexed faster.

The related rule that preserves years of SEO work: when a URL moves permanently, 301 (or 308 for endpoints where the method must not change, like POST endpoints). A redesign that maps old URLs to 404 instead of 301 drops your search traffic within weeks — I've watched it happen, and the fix is always the same retrospective: export the old URL list, redirect everything, verify each target returns 200.

Within redirects, the pair that matters:

301 vs 302: permanent vs temporary. 301 transfers ranking to the new URL; 302 does not. Browsers convert POST to GET after a 301.
307 vs 308: same meanings, but method and body are preserved. For APIs, 307/308 are usually the correct choice; for public web pages, 301 remains the standard.

The pair everyone underuses: 202 and 204

Two codes that make APIs honest:

202 Accepted — "I received your request and will process it, but it isn't done." If your POST enqueues a job for async processing, 202 is the truthful answer. Returning 200 when the work hasn't happened yet means your client thinks the email was sent when it's actually still in a queue that will retry at 3 AM.

204 No Content — "succeeded, and there's nothing to return." The clean response for DELETE, or any operation with no meaningful body. 204 also carries a subtle contract: the response must have no body. Returning 200 with an empty string is what most APIs do, and it forces clients to handle two shapes for the same outcome.

The general principle behind both: return the code that describes what actually happened, not the code that makes the client happy. Fake-200 APIs push complexity downstream into consumer code, where it multiplies.

4xx codes that are worth their tokens

429 Too Many Requests — you're rate limiting. Include a Retry-After header; well-behaved clients honor it, and your effective load drops immediately.
422 Unprocessable Entity — syntactically valid JSON, semantically wrong data (email field contains a phone number). Many APIs collapse this into 400, which forces clients to parse the error body to learn what kind of failure it was.
415 Unsupported Media Type — you sent XML to a JSON endpoint. Distinct from 400, and trivially cheap to check.
451 Unavailable For Legal Reasons — the takedown code, named after Fahrenheit 451. You'll rarely return it, but you should know why your favorite site vanished in some region.

When the server is lying: 502, 503, 504

The 5xx trio behind every "is it just me?" incident:

502 Bad Gateway — your proxy (nginx, the load balancer) reached the backend and got garbage back, or nothing. Usually means the backend crashed or is misconfigured. Read the proxy's error log, not just the app log.
503 Service Unavailable — deliberately refusing: overloaded, or in maintenance. This is the "back off" signal, and the right response from a circuit breaker.
504 Gateway Timeout — the backend is up but too slow. Different fix from 502: this one is about timeouts and slow queries, not crashes.

The debugging shortcut: 502/504 mean "the proxy couldn't talk to the app" and 503 means "the app or the operator chose to say no." Three different log files, three different fixes — which is why "the site is down" tickets get resolved so much faster when the first question asked is which exact 5xx.

A debugging workflow that works

Reproduce with curl, capture headers, not just the body
4xx? It's the request — validate payload, URL, auth header, Content-Type
5xx? It's the server — application log first, proxy log second
Read the response headers: Retry-After, Location, WWW-Authenticate, Allow usually contain the actual fix
Fix minimally, redeploy, retest with the exact same request

The habit that pays compound interest: save the full headers of every interesting failure. The status code names the problem class; the headers usually name the problem.

If you want a searchable list of all this while you work — including the lesser-known codes and which fix goes with which — I keep a free HTTP status code reference and a longer 1xx-to-5xx guide at IPCalcPlus. Both run entirely in the browser, no signup. The Port Checker is next to it for the other half of "is it the network or the app" debugging.

Which wrong status code do you see most often in the wild? My vote: 500 for expired tokens.

Five Cron Fields, One Trap: The Scheduling Bug Nobody Expects

yuanke215 — Sun, 27 Sep 2026 03:05:27 +0000

Every backend eventually grows a cron job. Backups at 2 AM, digests at 8 AM, health checks every five minutes. And every team eventually hits the same wall: the schedule that fires at a time nobody asked for, in a timezone nobody configured, on a day-of-week nobody intended.

Cron syntax is five fields. It fits on a sticky note. The bugs do not come from the syntax — they come from the three places where different implementations disagree with each other. This is a field guide to all of it.

The five fields, in one breath

 ┌───────────── minute (0-59)
 │ ┌───────────── hour (0-23)
 │ │ ┌───────────── day of month (1-31)
 │ │ │ ┌───────────── month (1-12 or JAN-DEC)
 │ │ │ │ ┌───────────── day of week (0-6 or SUN-SAT; 7 = Sunday too)
 * * * * *  command

Four operators cover 99% of real expressions:

* — every value in the field
, — list: 6,18 in hours = 6 AM and 6 PM
- — range: MON-FRI
/ — step: */15 in minutes = every 15 minutes

One subtlety worth internalizing: */15 starts at the field's zero (0, 15, 30, 45), but 5/15 starts at 5 (5, 20, 35, 50). The start value shifts the whole sequence — this is the difference between "aligned" and "offset" intervals, and it matters when you are spreading load across workers.

The trap: day-of-month OR day-of-week

Here is the bug I have now seen three times in production, always from a competent engineer, always written down as "cron is weird."

The expression 0 0 1 * 1 looks like it means "midnight on the first of the month, if it's a Monday."

In standard Unix cron, it means "midnight on the first of the month AND midnight on every Monday." The relationship is OR, not AND. That job fires ~48 times a year instead of ~1.

The rule, straight from the Vixie cron man page: when both the day-of-month and day-of-week fields are restricted (neither is *), the job runs when either matches. To get true AND logic you need Quartz-style syntax (0 0 1 ? * 1, where ? means "no specific value") or a guard in the script itself.

This single rule explains most "my cron job runs at the wrong time" mysteries. If your target platform is Quartz, Spring, or Jenkins, check their docs — most treat the two day fields differently from Unix cron, which is exactly why the bug survives code review: it worked on the engineer's machine, and their machine was running a different scheduler.

The L, W, and # extensions (and where they get you fired)

Modern schedulers — Quartz, Spring, AWS EventBridge, Kubernetes — support three extensions beyond classic cron:

L — last: 0 0 L * * = last day of the month; 0 0 * * 5L = last Friday
W — nearest weekday: 0 0 15W * * = weekday closest to the 15th
# — nth weekday: 0 0 * * 1#3 = third Monday

These are genuinely useful for monthly report jobs. They are also silently invalid in classic Vixie cron — the daemon treats them as syntax errors. Copy an L expression from a Quartz tutorial into /etc/cron.d/ and your job simply never runs. No warning, no email, just silence.

The portability rule: know your target before you copy the expression. The quick reference:

Platform	Fields	L/W/#	Timezone
Unix crontab	5	no	system
Quartz / Spring	6-7	yes	JVM
Kubernetes CronJob	5	yes	node (or `timeZone`)
AWS EventBridge	6	yes	UTC
GitHub Actions	5	no	UTC

Timezone and DST: the silent schedule-shifters

Two production incidents waiting to happen:

1. UTC defaults in the cloud. "0 9 * * " means 9 AM in *the scheduler's timezone. On GitHub Actions and AWS EventBridge, that is UTC. Your 9 AM daily report for the New York office goes out at 5 AM local. Nobody notices for a week because 5 AM email is just "early," until someone checks timestamps during a debugging session.

2. Daylight saving transitions. A job scheduled inside the spring-forward hour (e.g., 2:30 AM in a US timezone) does not run at all that day — the wall-clock time never happens. During fall-back, a job in the repeated hour runs twice. If "runs exactly once per day" is a billing or audit requirement, that's a defect. The standard fix: schedule critical jobs in UTC, or outside DST transition windows.

The general principle: for anything with an external SLA (backups, billing, cert renewal), write the cron expression in UTC and document that it is UTC. For anything user-facing, use a scheduler that supports explicit timezones and set it deliberately.

Six expressions worth memorizing

You will type these for the rest of your career:

0 2 * * * — nightly at 2 AM (backups, the classic low-traffic window)
*/5 * * * * — every 5 minutes (health checks, watchdogs)
0 9 * * MON-FRI — weekday mornings (reports, digests)
15 4 * * 0 — Sunday 4:15 AM (log rotation, cleanup)
0 */2 * * * — every 2 hours (syncs, cache refresh)
0 0 1 * * — first of the month (invoices, archives)

And the debug checklist when a job "didn't run": (1) is the daemon alive? (2) is the expression valid for this scheduler? (3) is the timezone what you think it is? (4) did a DST boundary swallow it? (5) check the scheduler's own log, not just your application log. In my experience the answer is (3) about half the time.

When I'm porting a schedule between platforms I run it through a free Cron Expression Generator first — it parses the expression, describes it in plain English, and shows the next 10 run times, so a UTC bug or an OR-logic trap is visible before it ships. It runs entirely in the browser. There's a longer reference writeup of everything above, including the full platform table, in the Cron Expressions Guide.

What's the worst scheduling bug you've shipped? Bonus points if the root cause was a timezone.

Stop Guessing Subnet Sizes: A Practical Mental Model for IPv4 Subnetting

yuanke215 — Sun, 27 Sep 2026 03:00:08 +0000

Most people learn subnetting as a pile of formulas: count the bits, subtract two, memorize the table. That works for exams, but it falls apart the moment you are standing in front of a real network with an IP like 10.0.5.130/27 and someone asks "what network is this on?"

This article is the version I wish someone had given me: a single mental model that turns every subnetting question into arithmetic you can do in your head, plus the three shortcuts that make it fast.

The one idea that makes subnetting click

An IPv4 address is 32 bits. A prefix like /26 means: the first 26 bits are the network, the last 6 bits are the host. That's it. Everything else follows from this sentence.

The consequences of those 6 host bits:

Total addresses in the subnet: 2^6 = 64
Usable hosts: 64 - 2 = 62 (the first address is the network ID, the last is the broadcast)

Notice you never needed the subnet mask 255.255.255.192. The prefix and the mask are the same statement in two languages — but the prefix form is the one that keeps the math obvious.

The block size shortcut (replaces binary math)

Here is the shortcut that removes binary from your daily life:

Block size = 256 minus the last non-255 octet of the mask.

/26 → mask ends in .192 → block = 256 - 192 = 64
/27 → .224 → block = 32
/28 → .240 → block = 16

Once you have the block size, subnets can only start at multiples of that block: 0, 64, 128, 192 for a /26. No exceptions. This is the single most useful fact in practical subnetting, because it means you can validate anyone's network design in seconds.

Worked example: which subnet is 10.0.5.130/27 on?

Block size = 32
List multiples: 0, 32, 64, 96, 128, 160...
130 falls between 128 and 160 → network is 10.0.5.128/27
Usable range: .129 to .158, broadcast .159

You just did the entire subnetting calculation — network address, usable range, broadcast — with nothing but subtraction.

Sizing: the question people actually get wrong

The exam question "how many hosts in a /28?" is easy. The real question is "I have 28 devices — which prefix do I pick?" And here people consistently fail in the same direction: too tight.

28 devices in a /27 (30 usable) = one printer installation from an outage
The rule I use: current need + 30-50% headroom, then round up to the next prefix

So 28 devices → aim for ~40 → /27 gives 30, not enough → /26 gives 62, take it. Wasted space is cheap. Re-numbering a live network is not.

Three mistakes that cause real outages

1. Misaligned boundaries. Someone configures 192.168.1.50/26 as a "new subnet." The mask zeroes the lower 6 bits, so the actual network is 192.168.1.0/26 — the same subnet as the engineering VLAN. The config "looks valid" but silently overlaps. Rule: every network address must be a multiple of the block size.

2. Mask mismatch after migration. You re-subnet a segment from /24 to /26, but one server keeps the old /24 mask. It ARPs for addresses outside its real subnet, fails, and the ticket says "network is slow" — because the truth (half the hosts are unreachable) is invisible to the application team. Change masks in a maintenance window, all devices, all at once.

3. Forgetting the two reserved addresses. .0 and .255 (or block edges on other prefixes) are not usable. A device handed a network or broadcast address fails in ways that depend on the OS — which means the symptom looks random.

When unequal subnets are the right answer

Equal subnets are a training exercise. Real networks have one 60-person department and three 8-person teams, and giving everyone a /26 wastes three quarters of your address space. The professional answer is VLSM (Variable Length Subnet Masking): allocate the biggest subnet first, then fit the smaller ones into what remains.

For a /24 with a 50-host engineering team, a 30-device guest network, and two small teams:

Need	Prefix	Network
Engineering (50)	/26	`192.168.1.0/26`
Guest (30)	/27	`192.168.1.64/27`
Team A (12)	/28	`192.168.1.96/28`
Team B (8)	/28	`192.168.1.112/28`

Everything fits in the bottom half, and the entire top half stays free for growth. Start big and work down — never the reverse, or you fragment the range.

Sanity-check any design in 60 seconds

Before you touch a router, verify three things:

Alignment — every network address is a multiple of its block size
No overlaps — sort subnets by network address; each broadcast must be below the next network address
Capacity — usable hosts ≥ current devices × 1.3

If all three pass, the design is sound. If any fails, you have just prevented an outage that would have been very hard to diagnose later — subnetting bugs don't show up as "subnetting bugs," they show up as "the network is weird."

If you want to verify any of these calculations without doing them by hand — or you inherited a network and want to reverse-engineer which subnet an address belongs to — I maintain a free Subnet Calculator that runs entirely in your browser (no signup, nothing leaves your device). There is also a CIDR converter for jumping between prefix and range notation, and a subnet mask cheat sheet worth pinning next to your terminal.

What's your subnetting horror story? The misaligned-boundary one in the comments section is guaranteed to be good.