HTTP Status Code

Quick Summary — TL;DR

An HTTP status code is a 3-digit number indicating whether a request succeeded (2xx), was rejected (4xx), or failed on the server (5xx).
For background jobs: 2xx means success, most 4xx errors are permanent (don't retry), and 5xx/408/429 are transient (retry with backoff).
A 429 (Too Many Requests) means you hit a rate limit — always respect the Retry-After header before retrying.

An HTTP status code is a three-digit number returned by a server in response to an HTTP request. It tells the client what happened: did the request succeed, did the client make an error, or did the server fail? For background jobs and webhooks, status codes determine whether a job is marked as successful, failed, or needs a retry.

The five categories

Range	Category	Meaning
1xx	Informational	Request received, processing continues
2xx	Success	Request was successful
3xx	Redirection	Further action needed (follow a redirect)
4xx	Client error	The request was malformed or unauthorized
5xx	Server error	The server failed to process a valid request

Codes that matter for background jobs

Success codes (don't retry)

Code	Meaning	Context
`200`	OK	The most common success response
`201`	Created	A resource was created (e.g., after a POST)
`202`	Accepted	The server accepted the request for async processing
`204`	No Content	Success, but no response body

Client errors (don't retry — fix the request)

Code	Meaning	Action
`400`	Bad Request	The payload is malformed — fix the data
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Authenticated but not authorized
`404`	Not Found	The endpoint doesn't exist — check the URL
`422`	Unprocessable Entity	Validation failed — fix the payload

Retryable errors (use exponential backoff)

Code	Meaning	Why retry
`408`	Request Timeout	Server didn't respond in time — may work on retry (see also webhook timeout)
`429`	Too Many Requests	Rate limited — back off and try later
`500`	Internal Server Error	Server-side bug or transient failure
`502`	Bad Gateway	Upstream server is down — often transient
`503`	Service Unavailable	Server overloaded or in maintenance
`504`	Gateway Timeout	Upstream server didn't respond — similar to timeout

The 429 special case

A 429 response means you've exceeded the API's rate limit. Many APIs include a Retry-After header that tells you exactly how long to wait. Always respect this header — retrying sooner will just get another 429.

How schedulers use status codes

An HTTP job scheduler like Recuro checks the status code after every execution:

2xx — job succeeded, log it, reset the failure counter
4xx (except 408, 429) — permanent failure, log it, don't retry
408, 429, 5xx — transient failure, retry with exponential backoff
No response (connection refused, DNS failure) — transient failure, retry

FAQ

What HTTP status code means success?

Any 2xx code means success. The most common is 200 (OK). For background jobs and webhooks, returning 200 or 204 tells the scheduler that the job was handled successfully.

Should I retry a 500 error?

Yes. A 500 Internal Server Error is usually transient — a deployment in progress, a temporary database issue, or an unhandled edge case. Retry with exponential backoff. If it persists after all retries, the job moves to the dead letter queue.

What does 429 Too Many Requests mean?

You've hit the API's rate limit. Wait for the duration specified in the Retry-After header, then try again.

Status codes drive the retry policy for background jobs. Retryable codes trigger exponential backoff, while permanent failures go to the dead letter queue. In systems with at-least-once delivery, a retryable status code means the job may execute more than once — making idempotency essential. A circuit breaker can prevent repeated calls when an endpoint consistently returns errors.