Refactor: Implement Unified Error Code Registry with Developer Documentation

[Smartdevs17]

Context

API errors return inconsistent formats and non-descriptive messages. Developers struggle to handle errors programmatically.

Current Limitation/Problem

Error codes are ad-hoc strings. The same error type may return different codes from different endpoints. There is no centralized error code registry.

Expected Outcome

A unified error code system with structured error responses, a centralized registry, auto-generated developer documentation, and SDK-friendly error types.

Acceptance Criteria

• Define error code format: ERR_<CATEGORY>_<SPECIFIC> (e.g., ERR_PAYMENT_INSUFFICIENT_FUNDS)
• Centralized error code registry with description, HTTP status, and resolution hints
• Standardized error response: { error: { code, message, details, requestId } }
• All endpoints return errors in standard format
• Error code discoverability: GET /api/errors returns full registry
• SDK generates typed error classes from registry
• OpenAPI integration: documented error responses per endpoint
• Error categorization: auth, validation, payment, blockchain, rate_limit, internal
• Error code deprecation with sunset timeline

Technical Scope

• packages/error-codes/ - error code registry package
• backend/src/middleware/error-handler.ts - standardized error response
• backend/src/errors/ - error classes
• packages/sdk/src/errors/ - typed error classes
• Auto-generation of error documentation
• Edge cases: error wrapping, sensitive information leakage, 3rd-party error mapping

[Mubking-dev]

@Mubking-dev has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi, I'm Mubaraq — a Full-Stack & Blockchain Developer with 3+ years of experience. I've reviewed this issue and I'm confident I can handle it. I'll submit a clean PR within 2–3 days. Please assign it to me!

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

[CeceOs92]

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

assign me this, will you?

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

[drips-wave]

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

🧑‍💻 @CeceOs92: 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 🌊