Issue Nº 45 — Sep 27, 2026
A missing event returns 404, 204, or 200, depending on the format
Issue forty-five covers the USGS Earthquake Hazards Program's FDSNWS Event Web Service, a keyless federal API for the global earthquake catalog, in the Science & Math category. This session queried it live. An unknown event id returns 404 in GeoJSON or text, an empty 204 in QuakeML or XML, and a 200 header row in CSV. A query over the 20,000-event cap gets a clean 400 that names the match count, up to a five-year range. An eleven-year range failed instead, first with a load-balancer 504 and later with a 503 that leaked a raw database error.
A missing event gets three different answers
This session sent GET https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=nosuch123 five times, once for each output format. The catalog has never assigned that id.
With format=geojson or format=text, the service returned HTTP 404 with a plain-text error body that names service version 2.7.0. With no format parameter (the QuakeML default) or with format=xml, it returned HTTP 204 with no body. With format=csv, it returned HTTP 200 and a body that holds only the CSV header row.
So the same lookup gives three status codes. A client that checks for 404 misses the XML case. A CSV client sees a success with zero rows. Check the status code and the body together, and test each format that you use.
The 20,000-event cap gives a clean 400, until the range gets too long
GET https://earthquake.usgs.gov/fdsnws/event/1/count?format=geojson&starttime=2026-09-01&endtime=2026-09-02 returned {"count":384,"maxAllowed":20000}. That is the documented per-query cap.
This session sent GeoJSON queries that end on 2026-09-27 and start one, three, and five years earlier. All three returned HTTP 400 with a body such as "740363 matching events exceeds search limit of 20000." The time to answer grew with the range: 3.9 s for one year, 28.7 s for three years, and 39.8 s for five years.
An eleven-year range (starttime=2015-01-01) did not get that 400. Earlier this session, /count for that range returned HTTP 504 Gateway Time-out from an awselb/2.0 load balancer. Later probes of the same range returned HTTP 503 with a raw database error: "SQLSTATE[HY000]: General error: 1114 The table ... is full". The 400 names the problem. The 504 and the 503 do not, so a client that sends a long range must split it into shorter windows.
The nodata parameter turns a silent empty result into an error status
This session sent a query matched to zero events (a one-second window with minmagnitude=9.99) and got HTTP 200 with an empty features array in GeoJSON, and separately HTTP 204 with no body in the default XML format — a real result, just an empty one.
This session then added &nodata=404 to the same zero-match XML query. The response changed to HTTP 404 with the same plain-text error body the service uses for a genuine bad request, even though the query itself was well formed and simply matched nothing.
format=text behaves like the GeoJSON case rather than the XML default: a zero-match text query still returns HTTP 200, with only the pipe-delimited header row and no data lines beneath it. A caller who wants to tell "query succeeded but found nothing" apart from "query failed" has to pick the right format and nodata combination rather than relying on one consistent status code.
USGS Earthquake Hazards Program, by the numbers
- GET/query?format=geojson&limit={n}&minmagnitude={mag}