How Can You Make a Command-Line JSON Error Reporter?
From the earlier reference collection. Read the current software blog.
A clear JSON error reporter validates response shape and turns structured failures into concise, actionable terminal output.
Decide what counts as an error
A command-line reporter should distinguish a transport failure from a valid response that describes an application error. A request can fail before any JSON arrives, return invalid JSON, or return valid JSON with an error object. These cases need different messages because their next steps differ. Define the expected response shape from the service contract rather than guessing from one sample.
For example, a response might contain an errors array whose entries have a code and a detail. The reporter should validate that the top-level value is an object, that errors is an array when present, and that each entry has the expected field types. A missing or wrongly typed field is a malformed response, not an empty list of errors.
Keep parsing and presentation separate
Parse the response first, then convert validated fields into a small internal representation, and only then print. This separation makes it easier to support multiple output formats later and prevents formatting rules from hiding validation problems. On the command line, concise human-readable output can go to standard error while a machine-readable mode writes structured JSON to standard output.
A useful line might read E_RATE_LIMIT: Request limit reached; retry later. The code helps a script or operator classify the issue, while the detail explains it in ordinary language. Preserve the original code exactly when it is valid text. If the detail is absent, report that clearly rather than inventing a description based on the code.
Handle awkward input safely
Treat the response body as untrusted input. Limit how much content the tool reads or prints, escape control characters, and avoid dumping secrets from headers or arbitrary server payloads. If the body is invalid JSON, report the parse failure and a short safe excerpt only if doing so helps diagnose the issue. A large HTML error page should not flood a terminal or be mistaken for structured application output.
Choose exit codes that reflect the outcome. For instance, zero can mean the response was valid and contained no reported errors, while nonzero values distinguish transport, parsing, and schema failures. Document the mapping so that shell scripts can use it reliably. Do not make exit status depend on incidental wording in a human-readable detail string.
Test the reporter as a user would
Create local fixtures for a valid response with no errors, one structured error, several errors, invalid JSON, a wrong top-level type, a missing code, and a non-text detail. Check both the printed message and the exit status. Include unusual characters in a detail to ensure terminal control sequences cannot alter the display.
The reporter’s job is to reduce the time between a failed request and a useful next action. Show enough context to identify the failure class, but keep the raw response available through an explicit diagnostic option when appropriate. A small, documented contract makes the program useful in both interactive troubleshooting and automated jobs.