error-recovery

Error Recovery — Core Skill

When things go wrong, AuthorAgent doesn't just report the error — it diagnoses the root cause, attempts automatic recovery, and remembers the fix for next time.

Error Categories

1. AI Provider Errors

Symptoms: API timeouts, rate limits, auth failures, model unavailability

Error Detected: Gemini API returned 429 (rate limited)

Diagnosis: Too many requests in short period (>60/min)
Recovery Strategy:
  1. ✅ Wait 30 seconds and retry (attempt 1 of 3)
  2. ⏳ Switch to DeepSeek as fallback provider
  3. ⏳ If all providers fail, queue the task for later

Lesson Stored: "Gemini rate limits at ~60 req/min.
Add 500ms delay between batch requests."

Recovery Playbook:

• 429 Rate Limited → Wait + retry → Switch provider → Queue
• 401 Unauthorized → Check API key in vault → Alert user if missing
• 503 Service Unavailable → Retry with backoff → Switch provider
• Timeout → Reduce prompt length → Retry → Switch provider
• Content filtered → Rephrase prompt → Retry without triggering content filter
• Context too long → Truncate prior results → Summarize context → Retry

2. Goal Execution Errors

Symptoms: Step failures, invalid AI output, parsing failures

Error Detected: Goal step "Create character profiles" failed
AI returned unstructured text instead of character profiles

Diagnosis: Prompt was too open-ended for structured output
Recovery Strategy:
  1. ✅ Reformulate prompt with explicit structure requirements
  2. ✅ Add output format example to prompt
  3. ✅ Retry with reformulated prompt

New prompt: "Create character profiles in this exact format:
NAME: [name]
AGE: [age]
ROLE: [protagonist/antagonist/supporting]
..."

Result: ✅ Step succeeded on retry

Recovery Playbook:

• Unstructured output → Add format constraints → Retry
• JSON parse error → Strip markdown fences → Extract JSON → Retry with stricter prompt
• Output too short → Request longer output → Increase max tokens → Retry
• Repeated failure → Skip step → Flag for user review → Continue goal
• Nonsensical output → Switch provider → Reduce temperature → Retry