Skip to content

Display API error messages instead of generic HTTP status codes #669

@crtahlin

Description

@crtahlin

Problem

When a Bee API request fails, swarm-cli displays only the generic HTTP status code instead of the descriptive error message returned by the API.

Example: Running swarm-cli stake deposit --bzz 10 when the node wallet has insufficient xBZZ balance:

? You are about to deposit a non-refundable stake of 10.0000000000000000 xBZZ, are you sure you wish to proceed? Yes
ERROR Request failed with status code 400

However, the Bee API does return a descriptive JSON error response:

{"message": "out of funds", "code": 400}

The user sees Request failed with status code 400 — which is unhelpful — instead of out of funds, which immediately tells them what to fix.

This applies to all API error responses, not just staking. The Bee API consistently returns a StatusResponse with a message field and an HTTP status code for every error, for example:

  • {"message": "insufficient stake amount", "code": 400}
  • {"message": "out of funds", "code": 400}
  • {"message": "insufficient stake to withdraw", "code": 400}
  • {"message": "simultaneous on-chain operations not supported", "code": 429}

None of these messages reach the user today.

Proposed Solution

1. Extract and display the API error message

When an HTTP request fails (e.g. Axios error), read error.response.data.message and display it prominently. The HTTP status code can still be shown as secondary context.

2. Suggested UX

Before (current):

ERROR Request failed with status code 400

After (proposed):

ERROR out of funds (HTTP 400)

Or for a more polished experience with actionable guidance:

ERROR Stake deposit failed: out of funds
  Hint: Check your wallet balance with `swarm-cli status`

3. Fallback behavior

If the response body doesn't contain a parseable message field (e.g. non-Bee upstream proxy errors), fall back to the current generic message so nothing breaks.

Impact

This is a significant UX issue because:

  • Users currently have to dig through Bee node Docker logs (docker logs <container> | grep post_stake_deposit) to understand what went wrong
  • The information needed to diagnose the issue is already in the API response — it's just not being shown
  • Many common errors (insufficient funds, minimum stake not met, simultaneous operations) have clear, actionable messages that would save users time and confusion

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions