Add docs/API_ERRORS.md listing every stable error code

[Baskarayelu]

Summary

Description, HTTP status, and typical remediation.

Background

We rely on this information internally but it is currently tribal knowledge. Writing it down lets reviewers verify behaviour against the documented intent, lets new contributors get productive without reading every commit, and lets the support team answer common questions without paging an engineer.

Acceptance criteria

• The change matches the summary above.
• The new document is linked from at least one existing top-level doc (README or docs/README).
• Examples in the document compile / run if applicable.
• Lint, type-check, and tests all pass locally.
• PR description references this issue with Closes #<this-issue>.

Implementation hints

• Audience: pick one (contributor / operator / downstream integrator) and write for them; do not try to address all three in the same doc.
• Prefer concrete examples over abstract definitions. Show a real entrypoint, request, or output rather than foo() placeholders.
• Cross-link from the README and from any related doc; orphaned docs rot fastest.
• Where the project ships generated docs (rustdoc, JSDoc, OpenAPI), keep this new content discoverable from the same starting point.

Repo-specific notes

• Run npx tsc --noEmit, npm test, and the security:scan / sbom:check scripts locally before pushing.
• Any new request or response shape must have a matching Zod schema and a regenerated OpenAPI entry.
• New env vars must be added to .env.example and to the relevant deployment doc.

Out of scope

• Unrelated refactors in adjacent files.
• Stylistic-only changes (formatting, renaming) that are not required by the fix.
• Anything beyond the acceptance criteria above; surface follow-ups as separate issues.

How to claim and submit

1. Comment on this issue saying you'd like to take it on; wait for a maintainer to assign you (avoids duplicated effort).
2. Open a PR that references this issue (Closes #<this-issue>).
3. Make sure CI is green and request review from a CODEOWNERS maintainer.
4. PRs that close this issue and pass review may qualify for a reward — see the MAYBE REWARDED label and the FWC26 campaign page.

---

Category: documentation  ·  Campaign: GrantFox OSS · Official Campaign | FWC26 · Maybe Rewarded

[tobemacauley-rgb]

@tobemacauley-rgb has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hey I would love to work on this issue

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

[posi14]

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

pls can you assign this issue to me, i can solve it

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

[Danto1606]

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

I would like to work on this

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

[Baskarayelu]

Great — @tobemacauley-rgb, this one's for you.

A few pointers:

• Reference this issue in the PR body with Closes #698
• Keep the change scoped to the acceptance criteria above
• Come say hi in our Discord: https://discord.gg/WC53JxDqx

[drips-wave]

Congratulations, @tobemacauley-rgb! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

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

[Baskarayelu]

@tobemacauley-rgb You were assigned to this issue because of your comment/activity here. Since no PR has been opened after 2+ days, I am unassigning you for now. Please open a draft PR first, then ask to be re-assigned if you want to keep working on it.

[drips-wave]

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

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