Skip to content

fix: make exit codes match the documented contract - #4

Merged
voska merged 2 commits into
voska:masterfrom
shbernal:fix/exit-codes
Oct 31, 2026
Merged

voska merged 2 commits into
voska:masterfrom
shbernal:fix/exit-codes

Conversation

@shbernal

Copy link
Copy Markdown
Contributor

The README promises exit 8 for retryable errors, but only hn status could return it. read and user turned every failure into exit 5, so a dropped connection looked like a deleted item. search and front exited 1. An agent couldn't tell when to retry.

Case Before After
read or user, network down 5 8
search or front, network down 1 8
429 or 5xx 1 or 5 8
hn front with no stories 0 3
hn status --json, API down 0 8

hn user now uses the Firebase API. Algolia answers 500 for an unknown user, which can't be told apart from an outage. Firebase answers null. The --json output keeps its fields.

I also dropped "no rate limits" from the README and AGENTS.md. I couldn't find an official limit, but community guides report about 10k requests an hour per IP, so the claim looked unsafe.

Checked with make test, golangci-lint, and live runs against the APIs, with a dead proxy for the network cases.

Network failures, rate limits and server errors now exit 8. Previously
`read` and `user` reported every failure as not found (5), and `search`
and `front` exited 1, so callers could not tell when to retry.

`hn user` moves to the Firebase API because Algolia answers 500 for
unknown users. An empty `hn front` exits 3, and `hn status --json` exits
8 when the API is down.
@voska

voska commented Oct 30, 2026

Copy link
Copy Markdown
Owner

This is the right fix. A dropped connection exiting 5 reads as a deleted item, which is exactly the case an agent needs to separate from an outage. Routing everything through one getJSON with tests for 404, 429, 5xx and a dead server is the right shape.

Firebase for hn user makes sense given Algolia's 500 on unknown users, and User only ever carried username, about and karma, so --json output stays the same. Agreed on dropping "no rate limits" too.

@voska
voska merged commit f53b723 into voska:master Oct 31, 2026
2 checks passed
@voska

voska commented Nov 5, 2026

Copy link
Copy Markdown
Owner

This shipped in v0.3.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants