Document http api error exposure

[sxlijin]

Pull Request Template

Thanks for taking the time to fill out this pull request!

Issue Reference

Please link to any related issues

• This PR fixes/closes #[issue number]
  This PR addresses a common user query regarding error handling for the BAML HTTP/REST API, as highlighted by a user asking "Hey, how to do error handling for REST api ?".

Changes

Please describe the changes proposed in this pull request

This PR introduces comprehensive documentation for error handling in the BAML HTTP API.

• New Documentation File: Created fern/01-guide/02-languages/rest-error-handling.mdx which details:
  • Consistent JSON error response format.
  • Mapping of HTTP status codes to error scenarios.
  • Detailed explanation of six specific error types: invalid_argument, client_error, client_http_error, validation_failure, finish_reason_error, and internal_error.
  • Guidance on handling authentication errors.
  • Best practices for error handling, including Python code examples for specific error type handling, retry logic with exponential backoff, and validation failure recovery using fixup functions.
  • Tips for debugging errors using debug endpoints, detailed logging, and interactive documentation.
  • Information on how errors are exposed in streaming (Server-Sent Events) responses.
• Documentation Navigation Update: Modified fern/docs.yml to restructure the "REST API (other languages)" section into a collapsible group, including "Getting Started" and the new "Error Handling" guide.
• Cross-References:
  • Added a tip in fern/01-guide/02-languages/rest.mdx to direct users to the new error handling guide.
  • Added a dedicated "Error Handling" section in fern/03-reference/baml-cli/serve.mdx with a link to the new guide.

Testing

Please describe how you tested these changes

• Unit tests added/updated
• Manual testing performed
• Tested in [environment]
  • baml-runtime unit tests were run and passed successfully.
  • The documentation structure and content were reviewed for accuracy and clarity.
  • The new navigation links and cross-references were verified to ensure they point to the correct documentation.

Screenshots

If applicable, add screenshots to help explain your changes

[Add screenshots here...]

PR Checklist

Please ensure you've completed these items

• I have read and followed the contributing guidelines
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

Additional Notes

Add any other context about the PR here

This PR aims to provide a clear and comprehensive guide for developers on how to anticipate, understand, and handle errors when interacting with the BAML HTTP API. It addresses a gap in the existing documentation and clarifies the error handling mechanisms implemented in engine/baml-runtime/src/cli/serve/error.rs.

---

Slack Thread

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
promptfiddle	Skipped			Sep 23, 2025 9:36pm

[github-actions]

https://sage-backend-5gelrq811-baml.vercel.app

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!