Guide

HTTP 4xx status codes for webhook and API endpoints, with a live test URL for each

From code 408 to 429, a 4xx status tells the caller its request was rejected. For webhooks and APIs each one changes what the sender does next: retry, back off or give up. This page explains the codes you will meet and gives you a live URL that returns any of them.

All docs

Every 4xx code at a glance#

A 4xx answer says the request itself was the problem. Most webhook senders don't read further than that: anything outside 2xx counts as a failed delivery and goes back on their retry schedule. So the code you return decides whether the same event comes back, and how soon.

CodeMeaningWhat a webhook sender usually does
400Bad Request: the body or headers could not be read.Retries, though the same request will fail again.
401Unauthorized: credentials or signature missing or wrong.Retries. Repeated failures can disable the endpoint.
403Forbidden: identified, but not allowed.Retries, or flags the endpoint as failing.
404Not Found: no handler at that path.Retries. Usually a wrong URL in the provider settings.
405Method Not Allowed: the route exists, not for this method.Retries until the route accepts POST.
408Request Timeout: the request did not arrive in time.Retries, often straight away.
409Conflict: clashes with what the server already has.Retries, so a duplicate keeps coming back.
410Gone: the endpoint was removed on purpose.Some senders take it as unsubscribe and stop.
413Content Too Large: the body is over the size limit.Retries with the same oversized body.
429Too Many Requests: slow down.Backs off, and well-behaved ones honor Retry-After.
499Client Closed Request (nginx): the caller hung up first.It already gave up and will retry.

Retry rules differ by provider, so check the docs for yours. The safe default is the same everywhere: answer 2xx as soon as the event is safely received, and use a 4xx only when you want the sender to know the delivery was rejected.

Code 408: Request Timeout#

HTTP code 408 means the server stopped waiting for the client to finish sending its request. The connection opened, the headers or body never fully arrived, and the server closed it. A client may send the same request again on a new connection, which is why a 408 is usually retried immediately.

With webhooks, the timeout that hurts is more often the other way around. The sender waits for your answer and gives up after a few seconds: GitHub allows 10 seconds, and Slack expects a reply to an event within 3. A handler that calls a model, writes to a slow database or sends email before answering will be marked as timed out even though it eventually succeeds, and the event is delivered again.

Acknowledge fast, work afterwards#

Check the signature, store the event, return 200, and only then do the slow part from a queue or background job. Agent handlers need this most, because one tool call can take longer than the sender will wait.

Test how your sender reacts to a timeout:

Terminal
# An endpoint that answers every request with 408
npx otterkit webhook --respond 408

# An endpoint that answers 200, but only after 9 seconds
npx otterkit webhook --respond-delay 9000

429 Too Many Requests#

A 429 means the receiver is rate limiting the caller. It may carry a Retry-After header, either a number of seconds or a date, that says when to try again.

  • If you receive webhooks: return 429 when you are overloaded rather than timing out. It tells the sender to slow down instead of failing outright.
  • If your agent calls an API: wait for Retry-After when it is present. Otherwise back off exponentially and add jitter, so that parallel workers don't all retry in the same instant.

A URL that rate limits every caller, and one that does it half the time:

Terminal
npx otterkit webhook --respond 429 --respond-header 'Retry-After: 30'

npx otterkit webhook --respond-script @rate-limit.js
rate-limit.js
export default {
  respond(req) {
    if (Math.random() < 0.5) return { status: 429, headers: { 'Retry-After': '5' } };
    return null; // everything else gets the default response
  },
};

401 and 403: signatures and auth failures#

401 Unauthorized means the request did not prove who sent it. 403 Forbidden means the server knows who is asking and refuses anyway. For a webhook handler, 401 is the usual answer to a signature that doesn't verify. When a handler starts returning it, the cause is nearly always one of these:

  • The signing secret is for another endpoint or environment, such as test and live.
  • The body was parsed before it was verified. Signatures cover the raw bytes, so verify first and parse after.
  • The timestamp is outside the tolerance, as with an old event replayed later.
  • A proxy in front of the handler rewrote the body or dropped the signature header.

OtterKit can check signatures as requests arrive, so you see which ones were genuine before your code runs, and it can send your local handler a correctly signed event to prove that your own check passes:

Terminal
# Mark every request valid, invalid or missing on arrival
npx otterkit webhook --verify stripe:whsec_abc123

# Fire a correctly signed event at your local handler
npx otterkit send stripe:payment_intent.succeeded 127.0.0.1:3000/webhooks/stripe \
  --secret whsec_abc123

See signature verification and Send & Verify Events.

405, 409, 413 and 499#

HTTP 405 Method Not Allowed#

The path exists but not for this method. Webhooks arrive as POST, so a route that only handles GET answers 405. The response should list what the route accepts in an Allow header. Fix it by exporting a POST handler on the route the provider calls.

HTTP 409 Conflict#

The request clashes with the current state, typically a record that already exists. Senders deliver at least once, so duplicates are normal. Don't answer a duplicate with 409: the sender reads it as a failure and sends the event again. Store each event's id, and when one you have already handled arrives, return 200 and do nothing.

413 Request Entity Too Large#

Now officially "Content Too Large": the body is bigger than the server or a proxy in front of it accepts. The limit is often a default nobody chose. Express's JSON parser stops at 100 kB and nginx at 1 MB. Raise the limit for the webhook route, since retries will carry the same body.

499 status code#

Not part of the HTTP standard. nginx writes 499 in its own log when the client closes the connection before the server has answered. Nobody receives a 499; it is the server-side view of the sender timing out. Treat it like a timeout and answer faster.

A live URL that returns the code you choose#

Retry logic is hard to test because real failures are rare. An OtterKit webhook endpoint answers with whatever you tell it to, on a public HTTPS URL, and records every request it receives:

Terminal
npx otterkit login
npx otterkit webhook --respond 408     # any status from 100 to 599
npx otterkit webhook --respond 413 --respond-body '{"error":"too large"}'

# Fail one path and leave the rest alone
npx otterkit webhook --respond-match path=/flaky --respond 409

The command prints a URL such as https://hook-e5f6g7h8.otterkit.app. Point your sender, your agent or curl at it and watch how it reacts. An endpoint costs 1 credit ($0.01) per hour it is live, and new accounts get 10 free credits.

Inspect and replay the requests that failed#

Once a request has reached OtterKit, you don't have to wait for the provider to send it again. List the failures, fix your handler, and replay the exact request into your local server:

Terminal
# Every captured request that was answered with a 4xx
npx otterkit inspect my-endpoint --status 4xx

# Send request #3 to the handler on port 3000
npx otterkit replay my-endpoint --index 3 --target 127.0.0.1:3000

Inspect Requests covers filters and HAR export, and Replay Requests covers editing a request before it is sent.

Next steps#