How Should a Sensor API Report a Failed Request?
From the earlier reference collection. Read the current software blog.
An API should describe failure through an unmistakable error state that cannot be mistaken for a valid sensor measurement.
Keep errors outside the measurement
A failed request should not return a plausible-looking temperature, water level, or other sensor value as a substitute for unavailable data. A value such as zero may be legitimate for some measurements, and a blank field may be interpreted as zero by a careless client. Returning either as if it were an observation can quietly contaminate charts and calculations.
Represent the outcome as an error using the API’s documented failure mechanism, and make clear that no measurement was returned. Include a concise machine-readable code and a human-readable explanation. For example, a client should be able to distinguish “station not found” from “upstream data temporarily unavailable” without parsing an ambiguous sentence.
Preserve useful context
A helpful failure response identifies the requested station or resource when safe and relevant, gives a time or request identifier for support, and indicates whether retrying may help. Avoid exposing secrets, internal file paths, or implementation details that do not help the caller. Keep the explanation stable enough for software clients to rely on the code, while allowing the prose to be improved.
If a request succeeds but the source has no recent observations, that is a different state from the request failing. Return an explicit empty or unavailable-data status according to the API contract rather than making it look like a transport error. Likewise, stale data can be returned as data only when its timestamp and freshness status remain visible.
Make clients handle the distinction
Document what a successful response looks like, what an error response looks like, and which fields are guaranteed in each case. A client should branch on the response status or documented error code before reading measurement fields. It should not infer success merely because a JSON document parsed or because a numeric field exists.
Consider a dashboard that requests a station reading. On success, it displays the value with its unit and observation time. On failure, it shows a clear unavailable state and keeps the last known value visibly labeled with its own timestamp if the design chooses to retain it. The old value must not appear to be the response to the failed request.
Design for recovery and diagnosis
State whether the failure is likely temporary when that information is known, and use retry guidance that matches the service’s behavior. Clients can avoid tight retry loops by applying a bounded delay and reporting persistent errors rather than repeatedly flooding the endpoint. Do not promise recovery times unless the service can support them.
A good error contract protects both the data and the people using it. Make failure obvious, preserve the distinction between missing and measured values, and give clients enough context to recover or explain what happened.