Error Handling in MCP: Designing Resilient Tool Workflows
Build robust MCP workflows that handle errors gracefully. This guide explains common error categories (authentication, validation, network, rate limits) and shows you how to design prompts that recover from failures with reusable recovery templates.
Error Categories
Authentication Errors (401, 403)
Auth Error Recovery
"If you get a 401 or 403 error when calling Corcava tools: 1. Tell me there's an authentication issue 2. Suggest checking the API key in the config 3. Don't retry the operation automatically 4. Wait for me to fix the auth issue"
Common causes:
- Invalid or expired API key
- Missing Authorization header
- Insufficient permissions
Validation Errors (400)
Validation Error Recovery
"If you get a validation error (400) when calling Corcava tools: 1. Show me the error message clearly 2. Identify which field is invalid 3. Suggest what the correct format should be 4. Ask if I want to retry with corrected data"
Common causes:
- Missing required fields
- Invalid field format (dates, IDs)
- Invalid field values
Network Errors
Network Error Recovery
"If you get a network error (connection failed, timeout) when calling Corcava tools: 1. Tell me there's a network issue 2. Wait a moment, then retry once 3. If retry fails, suggest checking network connectivity 4. Don't retry more than once automatically"
Common causes:
- Network connectivity issues
- Server timeout
- DNS resolution problems
Rate Limiting (429)
Rate Limit Recovery
"If you get a 429 rate limit error when calling Corcava tools: 1. Tell me the request was rate limited 2. Wait a few seconds before retrying 3. Reduce the number of tool calls (batch operations) 4. If still rate limited, suggest breaking the operation into smaller steps"
Common causes:
- Too many requests in short time
- Large batch operations
- Tool call loops
Recovery Prompt Templates
Template 1: Graceful Failure
Error Handling Pattern
"When calling Corcava tools, if you encounter any errors: 1. Show me the error message clearly 2. Explain what the error means in plain language 3. Suggest how to fix it 4. Ask if I want to retry or try a different approach 5. Don't retry automatically more than once"
This pattern: Handles errors gracefully, provides guidance, asks for direction
Template 2: Retry with Backoff
Retry Pattern
"If a tool call fails with a network error or timeout: 1. Wait 2 seconds 2. Retry the operation once 3. If it fails again, tell me and suggest checking network 4. Don't retry more than once"
This pattern: Handles transient errors, prevents infinite retries
Template 3: Fallback Strategy
Fallback Pattern
"If listing all tasks fails: 1. Try listing tasks for a specific project instead 2. If that works, show me those tasks 3. Tell me we can expand to more projects if needed 4. Suggest the issue might be with the full list query"
This pattern: Tries alternative approaches when primary fails
Complete Examples
Example 1: Resilient Task List
Error-Resilient Prompt
"List my tasks from Corcava due this week. If you encounter any errors: - For auth errors (401/403): tell me to check API key, don't retry - For network errors: wait 2 seconds and retry once - For rate limits (429): wait 5 seconds and retry once - For validation errors (400): show me the error and ask for correction - If all retries fail, tell me what went wrong and suggest next steps"
This pattern: Handles all error types with appropriate recovery
Example 2: Safe Batch Operation
Error-Resilient Batch Update
"Update 5 tasks to status 'in_progress'. If any update fails: - Show me which tasks succeeded and which failed - For failed tasks, show the error message - Ask if I want to retry the failed ones - Don't retry automatically—wait for my decision"
This pattern: Partial success handling, user-controlled retries
Best Practices
Error Handling Best Practices
- Show errors clearly: Always display error messages to the user
- Explain in plain language: Translate technical errors to understandable terms
- Suggest fixes: Provide actionable steps to resolve errors
- Limit retries: Don't retry indefinitely—set reasonable limits
- Handle partial success: For batch operations, show what succeeded/failed
- Ask before retrying: For critical operations, ask permission before retry
Related Resources
Troubleshooting Index
Complete troubleshooting guide
Tool Call Failures
Debug tool call issues
Rate Limiting
Handle rate limits
Batching Guide
Reduce tool calls
Build Resilient MCP Workflows
Use error handling patterns to create robust prompts that recover gracefully