firecrawl-incident-runbook

# Firecrawl Incident Runbook ## Overview Rapid incident response procedures for Firecrawl integration failures. Covers API outage triage, credential issues, credit exhaustion, crawl job failures, and webhook delivery problems. ## Severity Levels | Level | Definition | Response Time | Examples | |-------|------------|---------------|----------| | P1 | Complete failure | < 15 min | API returns 401/500 on all requests | | P2 | Degraded service | < 1 hour | High latency, partial failures, 429s | | P3 | Minor impact | < 4 hours | Webhook delays, some empty scrapes | | P4 | No user impact | Next business day | Monitoring gaps, credit warnings | ## Quick Triage (Run First) ```bash set -euo pipefail # 1. Test Firecrawl API directly echo "=== API Health ===" curl -s -w "\nHTTP %{http_code}\n" https://api.firecrawl.dev/v1/scrape \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com","formats":["markdown"]}' | jq '{success, error}' # 2. Check credit balance echo "=== Credits ===" curl -s https://api.firecrawl.dev/v1/team/credits \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" | jq . # 3. Check our app health echo "=== App Health ===" curl -sf https://api.yourapp.com/health | jq '.services.firecrawl' || echo "App unhealthy" ``` ## Decision Tree ``` Firecrawl API returning errors? ├─ 401: API key invalid │ → Verify key at firecrawl.dev/app, rotate if needed ├─ 402: Credits exhausted │ → Upgrade plan or ...