Parse structured JSON errors from gateway API responses

[antidmg]

Problem

The gateway now returns structured error JSON instead of bare status codes:

{"error": {"code": "CONFLICT", "message": "Application name already taken: foo"}}

The CLI wasn't parsing this — users saw empty or unhelpful messages:

error: API error (400):
error: API error (409):
error: API error (401):

After

error: A root-level README.md file is required for deployment
error: API error (409): Application name already taken: foo
error: Authentication required. Run `statespace auth login`.
error: Not found: environment

Summary by CodeRabbit

• Refactor
  • Centralized API error construction for consistent, clearer error messages.
  • Error responses now map common HTTP statuses to specific, user-facing messages (e.g., unauthorized, not found) and extract concise messages from response bodies.
  • Removed obsolete internal code paths to streamline error handling and reduce noise.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 13ade4e1-6cdd-4e35-b0f0-52015e137fd5

📥 Commits

Reviewing files that changed from the base of the PR and between 9f9fa9c and 5e6374d.

📒 Files selected for processing (2)

• binaries/statespace-cli/src/error.rs
• binaries/statespace-cli/src/gateway/client.rs

---

Walkthrough

Removed the unused Parse(String) variant from GatewayError and added pub(crate) fn from_response(status: u16, body: &str) to extract JSON error messages (from error.message or message), truncate fallback bodies, and map HTTP statuses to specific GatewayError variants; client code now calls this centralized constructor.

Changes

Cohort / File(s)	Summary
Gateway error enum binaries/statespace-cli/src/error.rs	Removed Parse(String) variant and #[allow(dead_code)]; added impl GatewayError with pub(crate) fn from_response(status: u16, body: &str) that extracts error.message or message from JSON (or truncates body) and maps 401→Unauthorized, 404→NotFound(message), others→Api { status, message }.
Gateway client usage binaries/statespace-cli/src/gateway/client.rs	Replaced inline GatewayError construction in check_api_response, parse_api_response, and parse_api_list_response with GatewayError::from_response(status, &body) and renamed local variable text→body.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Parse structured JSON errors from gateway API responses #126 — Modifies the same error handling paths and centralizes response-to-error construction in error.rs and gateway/client.rs.
• Fix secrets endpoints: use /api/v1 and shared response parser #106 — Related changes to gateway client response-handling (check_api_response / parse_api_response) that interact with the centralized error helpers.

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	❓ Inconclusive	The description clearly explains the problem, shows before/after examples, and details the implementation, but does not include testing checklist items from the template.	Complete the Testing section by checking off the applicable cargo commands (fmt, clippy, test) and confirm Docs section status.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: parsing structured JSON errors from gateway API responses.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch structured-api-errors

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@binaries/statespace-cli/src/gateway/client.rs`:
- Around line 380-402: Add unit tests for extract_error_message and
map_api_error: create tests that assert extract_error_message parses nested JSON
with {"error": {"message": "..."}}, parses flat {"message": "..."}, returns raw
text when body is non-JSON and that raw result is truncated to 512 chars, and
that map_api_error maps 401 to GatewayError::Unauthorized, 404 to
GatewayError::NotFound(message) preserving the message, and other statuses to
GatewayError::Api { status, message }. Use the function names
extract_error_message and map_api_error to locate code and craft minimal focused
tests for each branch.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: ea698b90-3ecd-4fb8-b027-0094d732280a

📥 Commits

Reviewing files that changed from the base of the PR and between 36b88ec and 49ef5d0.

📒 Files selected for processing (2)

• binaries/statespace-cli/src/error.rs
• binaries/statespace-cli/src/gateway/client.rs

💤 Files with no reviewable changes (1)

• binaries/statespace-cli/src/error.rs