Document the standard gateway/proxy error response envelope and error codes

[greatest0fallt1me]

Description

Callora returns errors through a consistent JSON envelope produced by the shared errorHandler (src/middleware/errorHandler.ts) using the typed error classes in src/errors/index.ts (BadRequestError 400, PaymentRequiredError 402, TooManyRequestsError 429, BadGatewayError 502, GatewayTimeoutError 504, etc.). README.md documents the validation envelope shape, but there is no single reference enumerating the gateway/proxy and billing error codes, their HTTP statuses, and when they occur — e.g. the proxy maps upstream failures to 502/504 (src/routes/proxyRoutes.ts:213-228) and billing maps Soroban RPC categories (INSUFFICIENT_BALANCE→402, TIMEOUT→504, others→502) in src/routes/billing.ts. This issue produces that reference.

Requirements and context

• Add a documentation page (e.g. docs/error-codes.md) cataloguing every error class in src/errors/index.ts: stable code, HTTP statusCode, meaning, and an example envelope (code, message, requestId, optional details).
• Document the gateway/proxy failure mapping: how src/routes/proxyRoutes.ts derives upstreamStatus and when it returns 502 (BAD_GATEWAY) vs 504, and note that the response body currently does not include the raw upstream status or Soroban revert reason (so integrators know what to expect).
• Document the billing Soroban error mapping in src/routes/billing.ts (insufficient balance → 402, timeout → 504, contract/network → 502).
• Cross-link from README.md (which already shows the validation-error example) to the new page.
• Non-functional: this is documentation-only; do not change runtime behavior. Where helpful, include curl-style examples consistent with the existing examples/ directory.

Acceptance criteria

• docs/error-codes.md lists every error class from src/errors/index.ts with code, status, and example.
• The proxy 502/504 derivation in src/routes/proxyRoutes.ts is documented, including the current omission of upstream status/revert reason from the body.
• The billing Soroban category-to-status mapping is documented.
• README.md links to the new page.
• All documented codes/statuses match the source (no invented codes).
• No source/runtime files are modified.

Suggested execution

1. Fork the repo and create a branch

git checkout -b docs/error-codes-reference

2. Implement changes — add docs/error-codes.md and a link from README.md.
3. Write/extend tests — documentation-only; run lint/typecheck/build to confirm nothing breaks.
4. Test and commit

npm run lint
npm run typecheck
npm run build

Example commit message

docs(errors): add gateway and billing error-code reference

Guidelines

No coverage change expected (documentation-only), but the existing 90%+ target (README.md) must not regress. Ensure every documented code is verified against src/errors/index.ts and the routing code before publishing. Timeframe: 96 hours.

[samsolo247]

Hi Maintainer,

I’m a smart contract and full-stack developer and would love to contribute to this issue. I’m an experienced contributor with hands-on expertise in Rust, Soroban, Cairo, and TypeScript.

I’m passionate about building secure, scalable blockchain solutions, with a strong emphasis on writing clean and maintainable code. Based on the scope of this issue, I’m confident I can deliver a complete solution within 24 hours of assignment.

I’d greatly appreciate the opportunity to contribute and help move this forward.