Implement structured API error schema with consistent error codes and documentation

[devJaja]

Summary

API errors vary in shape and code across endpoints. Some return { error: { message } }, others throw generic Error objects, and the frontend ApiError expects { statusCode, message, path }. A standardized, documented error schema is needed so clients can reliably handle failures.

Priority

P2

Files to work on

backend/src/api/middleware/errorHandler.ts
backend/src/errors/ (standardize)
backend/src/api/routes/
backend/docs/API_REFERENCE.md

Requirements

• Define canonical error schema: { error: { code, message, details?, path, correlationId } }
• Standardize error codes across the API:
  • VALIDATION_ERROR (400), UNAUTHORIZED (401), FORBIDDEN (403)
  • NOT_FOUND (404), CONFLICT (409), RATE_LIMITED (429)
  • UPSTREAM_UNAVAILABLE (502), VENICE_UNAVAILABLE (503), STELLAR_UNAVAILABLE (503)
  • INTERNAL_ERROR (500)
• Ensure errorHandler middleware maps all thrown errors to this schema
• Add correlationId to every error response (from request tracing)
• Document all error codes in docs/API_REFERENCE.md with examples
• Legacy error formats are aligned (audit all controllers for consistent errors)

Acceptance Criteria

• Every API error response conforms to { error: { code, message, path, correlationId } }
• Error code list is comprehensive and documented
• errorHandler catches thrown errors and maps them correctly
• VALIDATION_ERROR returned for zod validation failures
• VENICE_UNAVAILABLE returned when Venice circuit is open
• correlationId present in all error responses
• Frontend ApiError parsing works with the new schema
• docs/API_REFERENCE.md lists all error codes with usage examples

[ZeePearl56]

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

I would like to work on this issue

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

[Davichi-1]

@Davichi-1 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello Team I'd love to be assigned this issue. As a backend developer, I've experience across many frameworks, and I'm confident I'll be able to resolve this. Looking forward to it. Thanks

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

[isavaima8-alt]

@isavaima8-alt has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

hi pls can i work on this issue

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

[ajulaybeeb]

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

hi maintainer, i am a Full-Stack and web3 Developer, with 4+ years of experience. I have carefully read and understand the description of this issue, and i would like to take on this issue

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

[Stanley-Owoh]

@Stanley-Owoh has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Good day maintainer please assign this issue to me i can work on it immediately with positive results
Thank you

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

[Meeynarh1]

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

Hello Maintainer, this issue aligns well with my experience and interests. I’ve reviewed the requirements and can begin working on a solution immediately. Please consider assigning it to me.

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