4 ms·
TL;DR - API developers should make it so consumers have the necessary information and tools to know what's happening. If you're just returning a 404 with no oth
by latch 3y ago
TL;DR - API developers should make it so consumers have the necessary information and tools to know what's happening. If you're just returning a 404 with no other info, you have a bad API.
There's basic error handling/reporting that seems to transcend technology and architecture, and a big part of that is that errors should have unique error codes. In the context of a web API, both "route not found" and "resource does not exist" should return a 404, but each should have a unique `code` in the body:
{"code": 0, "err": "route not found"}
{"code": 1, "err", "user not found"}
For HTTP, the status code is often for general application development, and the error code is for debugging, though there can be overlap and it's completely fine if a client wants to implement custom logic based on `body.code`.
A validation error should look like:
{"code": 2, err: "invalid", "data": {
"username": [{"code": 100, "err": "required"}],
"password": [{"code": 101, "err": "must be at least 6 characters", "data": {"min": 6}}]
}}
The `code` always indicates what other data, if any, exists. Above, a code of 2 means there'll be a `data` field of errors. A validation error of `101` means there'll be a `min` field in `data`. `err` is an user-safe (developer friendly) description of the message which can always be regenerated from `code` + `data`.
For errors that aren't known ahead of a time (e.g. a server error), that should also have a distinct code, say 500, and the "data" field should contain an `error_id` which can be used to look up the error.
- DanHulton 3y agoAbsolutely. In fact, you're almost perfectly describing the JsonAPI standard for returning errors: https://jsonapi.org/format/#errors https://jsonapi.org/format/#errors One improvement I'd steal from theirs and drop in yours - constant (or enum) string codes. It's a lot more scannable when debugging/reviewing/maintaining than having to look up integer codes in a table.
- omegabravo 3y agoJust pointing out that codes make it easier to provide translations and ability to switch between error types with more confidence than string matching. Error codes should be accompanied by helpful messages so you don't have to look up the table.
- JimDabell 3y agoThere’s a standard format for errors in JSON described in RFC 7807: https://datatracker.ietf.org/doc/html/rfc7807 https://datatracker.ietf.org/doc/html/rfc7807 People shouldn’t invent their own custom error JSON when a standardised format will work.
- Izkata 3y ago> In the context of a web API, both "route not found" and "resource does not exist" should return a 404, but each should have a unique `code` in the body I forget if it was 404 or something else, but you should check if it actually works first. One of our sites did exactly as you suggest here, and it worked totally fine in development (django "runserver"), but didn't work in production (wsgi behind apache). Turned out with that HTTP code, apache was discarding the body.
- kiitos 3y agoThis makes sense if your web API asserts that all responses are JSON responses, and if it provides a schema for responses somewhere as a contract. But, in general, it's totally fine to return a 404 with no other info. That's a totally acceptable API.