docs: add API errors documentation page

[amikofalvy]

Summary

• Add documentation for Problem Details (RFC 9457) error responses at /api-reference/errors
• Document all error codes with anchors (#bad_request, #unauthorized, #forbidden, #not_found, #conflict, #unprocessable_entity, #internal_server_error)
• Update ERROR_DOCS_BASE_URL to point to the correct docs URL (https://docs.inkeep.com/api-reference/errors)

Test plan

• Verify the errors page renders correctly at /api-reference/errors
• Verify anchor links work for each error code
• Confirm the page appears in docs navigation under API Reference

[changeset-bot]

⚠️ No Changeset found

Latest commit: 80c42a7

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
agents-docs	Ready	Preview	Comment	Dec 4, 2025 6:14pm
agents-manage-api	Ready	Preview	Comment	Dec 4, 2025 6:14pm
agents-manage-ui	Ready	Preview	Comment	Dec 4, 2025 6:14pm
agents-run-api	Ready	Preview	Comment	Dec 4, 2025 6:14pm

[claude]

Claude finished @amikofalvy's task —— View job

---

PR Review: API Errors Documentation

After conducting a comprehensive technical and architectural review of this PR, I have several observations and recommendations across different dimensions of code quality, system design, and customer experience.

✅ Strengths

Technical Implementation

• Excellent RFC 9457 compliance: Properly implements Problem Details for HTTP APIs standard with correct content type and field structure
• Consistent error code mapping: Perfect alignment between documentation and ErrorCode enum in packages/agents-core/src/utils/error.ts:5-13
• Well-structured documentation: Clear format with consistent sections, anchors, and examples

System Design

• Backward compatibility preserved: Maintains legacy error object alongside RFC 9457 fields
• Comprehensive coverage: Documents all error codes defined in the system
• Good developer experience: Includes practical TypeScript example for error handling

🔍 Areas for Consideration

System Design & Architectural Concerns

1. URL Anchor Inconsistency (Medium Priority)

• Issue: Documentation uses underscored anchors (#bad_request) but the error utility references hyphenated ones (#${code} → #not_found)
• Evidence: packages/agents-core/src/utils/error.ts:95 constructs URLs like ${ERROR_DOCS_BASE_URL}#not_found
• Impact: Broken links when users click error documentation links in API responses
• Recommendation: Either change documentation anchors to match code or update code to use underscores

2. Incomplete Error Code Coverage (Low Priority)

• Issue: Documentation covers 7 error codes, but I notice the system might have more granular error scenarios
• Consideration: Are there domain-specific errors (e.g., agent configuration errors, tool execution failures) that warrant documentation?

Documentation Quality & Consistency

3. Navigation Integration

• Missing: No evidence that the new /api-reference/errors page appears in documentation navigation
• Recommendation: Ensure the page is properly integrated into the docs structure and sidebar navigation

4. Example Consistency

• Issue: Example shows requestId: "req_1234567890" but field is documented as optional
• Recommendation: Consider showing both with and without optional fields, or clarify when they're typically included

Customer Experience & Usability

5. Error Resolution Guidance

• Strength: Each error includes resolution steps
• Enhancement opportunity: Consider adding links to specific documentation sections (e.g., authentication docs for 401 errors)
• Missing: No guidance on distinguishing between client vs. server errors for retry logic

6. SDK Integration Considerations

• Gap: Documentation doesn't mention how different client SDKs should handle these error formats
• Consideration: Will client libraries need updates to parse RFC 9457 format properly?

Development Workflow

7. Changeset Requirement

• Issue: Changeset-bot indicates no changeset found
• Analysis: Based on .changeset/config.json:10, @inkeep/agents-docs is in the ignore list, so documentation changes don't require changesets
• Verdict: This is intentionally configured - no action needed

8. Type Alignment

• Verification needed: Ensure OpenAPI schema generation reflects the documented error format
• Code reference: packages/agents-core/src/utils/error.ts:27-58 defines the schema

🎯 Specific Recommendations

High Priority

1. Fix URL anchor mismatch: Update either documentation anchors or error utility to ensure consistent linking

Medium Priority

2. Add cross-references: Link 401 errors to authentication documentation
3. Enhance examples: Show complete request/response flow including headers
4. Navigation integration: Verify the errors page appears in docs sidebar

Low Priority

5. Consider error categorization: Group errors by functional area (auth, resources, validation, system)
6. Add troubleshooting section: Include common debugging steps and support contact information

🔄 Next Steps

The core implementation is solid and follows best practices. The primary concern is ensuring the URL anchors work correctly for users clicking error links. Consider testing the full flow from API error response to documentation page.

This PR successfully establishes a strong foundation for API error documentation that follows industry standards while maintaining backward compatibility.