Picking the right code for an API response
Clients decide what to do from the status code before they read the body, so a precise code saves everyone time:
- 201 after creating something, with a Location header pointing to it; 204 when there is nothing to return.
- 400 when the request cannot be read at all; 422 when it can be read but a field fails validation.
- 401 when no valid login or token was sent; 403 when the caller is known but not allowed.
- 404 for an id that does not exist; 410 for something deleted on purpose.
- 409 when the change clashes with the current state, such as a username that is already taken.
- 429 with a Retry-After header when a client goes over its rate limit.
Avoid answering an error with 200 and a message such as {"error": true} in the body. Monitoring tools, caches and client libraries all treat a 200 as success, so the failure goes unnoticed.
Redirects and search rankings
Use 301 or 308 when a page has moved for good, for example after changing your URL structure or moving from http to https. Search engines transfer the old page’s rankings to the new address and, over time, show only the new one. Use 302 or 307 for short-lived moves, such as sending visitors to a sale page for a week.
The difference between the two pairs is the method. A browser may follow a 301 or 302 with a GET even if the original request was a POST, while 307 and 308 keep the method and body. For API endpoints that move, 308 is the safe choice.
Keep redirect chains short. Each hop adds a round trip, and crawlers may stop following after several. Point old URLs straight at their final destination instead of through a list of older ones.
Telling 502, 503 and 504 apart
All three come from a proxy, load balancer or CDN that sits in front of the application, and each points to a different cause:
- 502 Bad Gateway: the application server sent nothing usable. It has crashed, is restarting, or the proxy points to the wrong port.
- 503 Service Unavailable: the server is up but refusing work, during maintenance or when every worker is busy.
- 504 Gateway Timeout: the application accepted the request but did not finish in time, usually because of a slow database query or an external API that hangs.
A 500, by contrast, comes from the application itself and means its code threw an error. The server’s error log names the line.
Soft 404s and other mistakes search engines notice
A “soft 404” is a page that says “not found” or shows an empty search but returns 200. Google treats it as missing anyway and reports it in Search Console, while the page wastes crawl time. Return a real 404 or 410 for pages that no longer exist, and redirect only when there is a close replacement, not to the home page.
For planned downtime, send 503 with a Retry-After header rather than a maintenance page with 200. Crawlers then come back later instead of indexing the maintenance message.
Use the search box above to filter the list by number or by any word in a description, such as “timeout” or “cache”. Each code also has its own link, so you can share the address of a single entry, such as #429.