Figma Incident Runbook
Overview
Rapid incident response procedures for Figma REST API integration failures. Covers triage, mitigation, and postmortem for the most common failure modes.
Prerequisites
- Access to application logs and metrics
- Figma PAT for health checks
- Communication channel (Slack, PagerDuty)
Instructions
Step 1: Quick Triage (First 5 Minutes)
#!/bin/bash
echo "=== Figma Incident Triage ==="
echo -n "Figma Status: "
curl -s https://www.figmastatus.com/api/v2/status.json 2>/dev/null \
| jq -r '.status.description // "Cannot reach status page"'
echo -n "Auth Check: "
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
-H "X-Figma-Token: ${FIGMA_PAT}" \
https://api.figma.com/v1/me)
echo "$HTTP_CODE"
echo -n "File Access: "
curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
"https://api.figma.com/v1/files/${FIGMA_FILE_KEY}?depth=1" \
| jq -r '.name // "FAILED"'
echo "Rate Limit Headers:"
curl -s -D - -o /dev/null \
-H "X-Figma-Token: ${FIGMA_PAT}" \
https://api.figma.com/v1/me 2>/dev/null \
| grep -iE "(retry-after|rate-limit|figma)" || echo "No rate limit headers"
Step 2: Decision Tree
API returning errors?
├── 403 Forbidden
│ ├── Token expired (>90 days) → Rotate PAT immediately
│ ├── Wrong scopes → Regenerate with correct scopes
│ └── File not shared → Check file permissions
│
├── 429 Rate Limited
│ ├── Retry-After < 60s → Wait and retry automatically
│ ├── Retry-After > 300s → Reduce request volume
│ └── X-Figma-Rate-Limit-Type: low → Consider upgrading plan
│
├── 404 Not Found
│ ├── File deleted → Check with file owner
│ ├── Wrong file key → Verify FIGMA_FILE_KEY
│ └── API path wrong → Check endpoint documentation
│
├── 500/503 Server Error
│ ├── status.figma.com shows incident → Wait for resolution
│ ├── Intermittent → Retry with backoff
│ └── Persistent → Contact Figma support
│
└── Network Error (ECONNREFUSED, timeout)
├── DNS resolution failing → Check DNS config
├── Firewall blocking → Verify outbound HTTPS to api.figma.com
└── TLS error → Check Node.js version (18+ required)
Step 3: Immediate Mitigation
For 403 (Token Expired):
gh secret set FIGMA_PAT --body "figd_new-token-here"
echo -n "figd_new-token" | gcloud secrets versions add figma-pat --data-file=-
gcloud run services update my-service --update-secrets="FIGMA_PAT=figma-pat:latest"
fly secrets set FIGMA_PAT=figd_new-token
For 429 (Rate Limited):
const EMERGENCY_MODE = process.env.FIGMA_EMERGENCY === 'true';
async function safeFigmaCall<T>(
path: string,
critical: boolean = false
): Promise<T | null> {
if (EMERGENCY_MODE && !critical) {
console.warn(`Figma call skipped (emergency mode): ${path}`);
return null;
}
return figmaFetch(path);
}
For 500/503 (Figma Down):
async function getTokensWithFallback() {
try {
return await extractTokensFromFigma();
} catch (error) {
console.warn('Figma unavailable, serving cached tokens');
const cached = await readFile('output/tokens.json', 'utf-8');
return JSON.parse(cached);
}
}
Step 4: Communication
## Internal Notification (Slack)
**Figma Integration Alert**
- Status: INVESTIGATING / MITIGATED / RESOLVED
- Impact: [Design token sync paused / Asset export failing]
- Cause: [403 expired token / 429 rate limit / Figma outage]
- Action: [Rotating token / Reducing request rate / Waiting for Figma]
- ETA: [Next update in 15 min]
## External (if applicable)
Design system updates may be delayed due to a temporary issue
with our Figma integration. Cached data is being served.
Step 5: Postmortem Template
## Figma Incident Postmortem
**Date:** YYYY-MM-DD
**Duration:** X hours Y minutes
**Severity:** P1/P2/P3
### Summary
[One sentence: what happened and what was the impact]
### Timeline
- HH:MM UTC - First alert fired (describe alert)
- HH:MM UTC - On-call acknowledged
- HH:MM UTC - Root cause identified
- HH:MM UTC - Mitigation applied
- HH:MM UTC - Full resolution confirmed
### Root Cause
[Technical explanation, e.g., "PAT expired after 90 days without rotation"]
### Action Items
- [ ] Set up PAT rotation reminder at 80-day mark
- [ ] Add 403 alert to PagerDuty
- [ ] Implement cached fallback for token data
Output
- Issue identified via triage script
- Root cause determined from decision tree
- Mitigation applied (token rotation, fallback mode, etc.)
- Stakeholders notified
- Postmortem documented
Error Handling
| Issue | Cause | Solution |
|---|
| Can't reach status.figma.com | Network issue | Try from different network or mobile |
| Triage script fails | PAT not set | Set FIGMA_PAT before running |
| Fallback data stale | Last cache too old | Set up regular cache refresh |
| Alert not firing | Missing metrics | Verify Prometheus scrape config |
Examples
Triage "the design token sync is failing" in under a minute (Step 1):
curl -s -o /dev/null -w '%{http_code}\n' -H "X-Figma-Token: ${FIGMA_PAT}" https://api.figma.com/v1/me
curl -s -o /dev/null -w '%{http_code}\n' -H "X-Figma-Token: ${FIGMA_PAT}" \
"https://api.figma.com/v1/files/${FIGMA_FILE_KEY}?depth=1"
/v1/me | file probe | Read as |
|---|
| 200 | 200 | Our pipeline bug — not an API incident |
| 200 | 403/404 | File access changed — check sharing/scopes |
| 401 | any | Token revoked or expired — rotate now |
| 429 / 5xx | 429 / 5xx | Figma-side — mitigate per Step 3, check status.figma.com |
Decision tree and mitigation actions: references/decision-tree.md, references/immediate-mitigation.md; postmortem scaffold: references/postmortem-template.md.
Resources
Next Steps
For data handling, see figma-data-handling.
