Skip to content

docs(output): say that API error codes are kept in JSON errors - #132

Open
tee8z wants to merge 1 commit into
masterfrom
docs/json-api-error-codes
Open

tee8z wants to merge 1 commit into
masterfrom
docs/json-api-error-codes

Conversation

@tee8z

@tee8z tee8z commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

This PR adds an Errors section to the output reference. It gives:

  • An example JSON error envelope for an API rejection.
  • The fields to branch on: error.detail.http_status and error.detail.data.error.type or .code. The API sends these and the CLI keeps them unchanged. The CLI only replaces secret values with [REDACTED].
  • That exit_code is the CLI's failure class (3 for 401 and 403, 1 for other API errors), not the HTTP status.
  • That message and hint are written for people, so scripts must not match on them.
  • The limits: a body that is not JSON is omitted and its status is only in message. A request that gets no response has no http_status.

Each claim matches src/api.rs (ErrorDetail::Http built from the response body) and src/output.rs (report_error). Integration tests assert it: report["error"]["detail"]["data"] == rejection, report["error"]["detail"]["http_status"], and HTTP 403: non-JSON response omitted.

Checks

  • Diff reviewed against master. It changes docs only (16 insertions, 1 deletion in docs/reference/output.md).
  • The cargo verification gate and the CRAP report were not run, because no file in src/ or tests/ changed and no test reads output.md.
  • No CHANGELOG.md line: the CLI's behavior does not change.

@tee8z tee8z self-assigned this Oct 31, 2026
@tee8z
tee8z requested a review from thebrandonlucas October 31, 2026 15:33
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.

1 participant