CONV-316: Document standard API errors

[menvil]

Summary

• Adds ErrorResponse and ErrorObject schemas with all standard error codes
• Adds reusable UnauthorizedError, ValidationError, NotFoundError response components
• Documents 10 machine-readable error codes in ErrorObject.code description

Test plan

• Test written first — fails before schemas added
• composer test passes (605 tests)

🤖 Generated with Claude Code

---

Summary by cubic

Standardize API error responses in the OpenAPI spec so clients can rely on consistent, machine-readable codes. Addresses Linear CONV-316.

• New Features
  • Added ErrorResponse and ErrorObject schemas with code, message, and details.
  • Documented 10 error codes for common failure cases.
  • Added reusable responses: UnauthorizedError, ValidationError, NotFoundError.
  • Expanded ApiKeyBearer description with an example Authorization header.

^{Written for commit 9edbbe0. Summary will update on new commits.}

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• release

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: baa1e322-f2f2-4e61-b560-bf8b1bef8e8e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/CONV-316-document-standard-api-errors

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}