Docs for retryable errors

[shagun-singh-inkeep]

No description provided.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0cebcbe

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	Review	Updated (UTC)
agents-docs	Ready	Preview, Comment	Jan 5, 2026 7:53pm
agents-manage-api	Ready	Preview, Comment	Jan 5, 2026 7:53pm
agents-manage-ui	Ready	Preview, Comment	Jan 5, 2026 7:53pm
agents-run-api	Ready	Preview, Comment	Jan 5, 2026 7:53pm

[claude]

Claude finished @shagun-singh-inkeep's task —— View job

---

PR Review: Docs for retryable errors

Review Tasks:

• Read the modified troubleshooting.mdx file to understand changes
• Research existing documentation patterns and standards
• Analyze content quality, accuracy, and consistency
• Provide comprehensive review feedback
• Check for customer impact and user experience considerations

Summary

This PR adds a new "Error Retry Behavior" section to the troubleshooting documentation, documenting the system's automatic retry mechanisms with exponential backoff for HTTP errors and network failures. The addition is valuable and addresses an important gap in user-facing documentation about system resilience behavior.

Technical Review

✅ Strengths

Content Accuracy: The documented HTTP status codes (429, 500, 502, 503, 504) and network errors precisely match the actual implementation found in the codebase (agents-run-api/src/a2a/client.ts:58, packages/agents-manage-mcp/src/lib/retries.ts).

Documentation Structure: The addition follows established patterns with a clear heading, concise explanation, and well-formatted tables for easy reference.

SEO Enhancement: Keywords were appropriately updated to include "retry, retryable errors, error handling" making this content discoverable.

⚠️ Areas for Improvement

1. Technical Precision & Context (Medium Priority)

The current documentation states "When calling agents the system automatically retries..." which is imprecise. The retry behavior is actually more nuanced:

• A2A (Agent-to-Agent) communication has retry logic with 1.5x exponential backoff
• MCP tool connections have separate retry configuration (3 retries max, 1.5x growth factor)
• Context Fetchers do NOT implement retry logic despite being mentioned in the troubleshooting guide

// Current (imprecise)
When calling agents the system automatically retries certain errors

// Suggested improvement
The system automatically retries certain errors during agent-to-agent communication and MCP tool interactions using exponential backoff.

2. Incomplete Network Error Coverage (Low Priority)

The implementation analysis shows ECONNREFUSED and ENOTFOUND are mentioned in docs but not explicitly handled in the current HTTP error detection logic (packages/agents-manage-mcp/src/lib/http.ts:260-282).

Consider either:

• Removing these from the list until implemented
• Adding a note about which components implement which retries

3. User Actionability (Medium Priority)

The section tells users what the system does but doesn't explain what they should expect or do. Consider adding:

## Error Retry Behavior

The system automatically retries certain errors during agent-to-agent communication and MCP tool interactions using exponential backoff. **These retries happen transparently and may cause brief delays in agent responses.**

### User Impact
- **Temporary slowdowns**: Responses may take longer during network issues or rate limiting
- **Eventual consistency**: Most transient errors resolve automatically without user intervention
- **Error escalation**: If retries are exhausted, the error will surface in the timeline error cards

[existing content continues...]

### When Retries Don't Help
If you see persistent errors for:
- Authentication failures (401/403)
- Resource not found (404) 
- Client errors (4xx except 429)

These typically require configuration changes rather than automatic retry resolution.

Architecture & System Design Review

✅ Follows Existing Patterns

The documentation follows the established troubleshooting guide structure and appropriately cross-references other sections (timeline, error cards).

⚠️ Missing Integration Opportunities

Relationship to Runtime Limits: This retry documentation should cross-reference the Configure Runtime Limits page since many of these retry constants are configurable via environment variables.

Connection to Error Debugging Workflow: The retry section appears after context fetcher issues but before the end. Consider if it should be earlier in the troubleshooting flow since understanding retry behavior helps interpret what users see in timelines.

Customer Experience Considerations

✅ Positive Impact

• Reduced Support Load: Users understand why some errors resolve automatically
• Better Debugging: Knowing about retries helps users interpret timeline delays
• Transparency: Clear explanation of system behavior builds trust

⚠️ Potential Confusion Points

Expectation Management: Users might expect retries to solve all errors. The documentation should clarify which errors are NOT retried (4xx client errors, authentication failures, etc.).

Timeout Implications: Users should understand that retries can extend overall request time, especially with exponential backoff.

Minor Issues

Missing Changeset: The changeset bot indicates no changeset was added. For documentation updates, consider if this should increment the @inkeep/agents-docs package version.

Table Formatting: The table structure is clean and accessible.

Writing Quality: Content is clear, concise, and technically accurate.

Recommendations

High Priority:

1. Clarify the scope of retry behavior (A2A communication vs. Context Fetchers)
2. Add user impact section explaining what to expect

Medium Priority:

1. Cross-reference runtime configuration documentation
2. Consider adding a "When Retries Don't Help" section for non-retryable errors

Low Priority:

1. Align documented network errors with actual implementation
2. Consider changeset for documentation versioning

Overall Assessment

This is a solid documentation addition that fills an important gap in user understanding of system behavior. The technical accuracy is high, and the format follows established patterns. With the suggested refinements around scope clarification and user guidance, this will be a valuable troubleshooting resource.

The changes demonstrate good engineering practice by documenting system resilience features that users encounter but may not understand.

---

[github-actions]

🔎💬 Inkeep AI search and chat service is syncing content for source 'Inkeep Agent Framework Docs'