Normalize Soroban RPC errors in `sorobanBilling.ts` into stable API error codes for `/api/billing/deduct`

[greatest0fallt1me]

Description

src/services/sorobanBilling.ts calls the configured Soroban RPC balance/deduct functions, but RPC failures surface inconsistently to /api/billing/deduct. This backend task maps RPC and network errors to the stable error types in src/errors/index.ts (e.g. PaymentRequiredError, BadGatewayError) so clients get predictable responses.

Requirements and Context

• Categorize Soroban RPC failures (insufficient balance, timeout, contract error, network) into stable error codes.
• Apply categorization in the /api/billing/deduct handler in src/routes/billing.ts.
• Preserve idempotency behavior keyed by requestId.
• Must be secure, tested, and documented
• Should be efficient and easy to review

Suggested Execution

1. Fork the repo and create a branch

   git checkout -b task/soroban-error-normalization

2. Implement changes
   • src/services/sorobanBilling.ts — classify RPC errors
   • src/routes/billing.ts — map to error types
   • src/errors/index.ts — add codes if needed
3. Test and commit
   • npm test -- src/services/sorobanBilling.test.ts
   • Cover edge cases
   • Include test output and notes in the PR

Example commit message

task: normalize Soroban RPC errors to stable codes

Acceptance Criteria

• Insufficient balance maps to 402, timeout to 504, contract/network to 502
• Error codes are stable and documented
• Idempotent deduct behavior is preserved

Guidelines

• Minimum 90% test coverage with Jest
• Clear documentation and inline comments
• Timeframe: 96 hours

[icodeBisola]

@icodeBisola has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Kindly assign I have ETC of 2-3, confident im the best fit to resolve this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @icodeBisola to this issue.

[drips-wave]

Congratulations, @icodeBisola! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @icodeBisola: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊