Add paid-route error taxonomy for analytics and CLI output

[emrekayat]

Why this matters

When a paid route fails, reviewers and operators need to know whether it was a payment issue, provider issue, validation issue, or internal error. A small taxonomy makes failures easier to trust and debug.

Scope

Add a typed failure code to paid-route responses and persisted analytics records where possible:

• payment_required;
• payment_invalid;
• provider_timeout;
• provider_failed;
• invalid_query;
• internal_error.

Suggested files:

• apps/api/src/routes/protected.ts
• apps/api/src/lib/persistence.ts
• apps/agent-client/src/client.ts
• packages/shared/src/schemas.ts

Acceptance criteria

• Paid-route failures return a stable errorCode without leaking secrets.
• Analytics can store the code for failed paid attempts when available.
• CLI prints the code in a compact, human-readable line.
• Tests cover at least validation failure and provider failure paths.
• Existing API and agent-client tests pass.

Wave complexity

High - adds operational credibility for paid-query failure handling.

[jethrojohn739-max]

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

Hi maintainer, I have read and understood the issue requirements and checked th

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

[oscar24357]

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

Hello maintainer I'd love to work on this issue, please assign me to it.

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

[Micheal-Blessed]

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

Let me work on this

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

[drips-wave]

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

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