Figma Production Checklist

Overview

Complete checklist for deploying Figma API integrations to production, covering authentication, error handling, rate limits, monitoring, and rollback.

Prerequisites

• Staging environment tested and verified
• Production PAT or OAuth credentials ready
• Monitoring infrastructure available

Instructions

Step 1: Authentication & Secrets

• ] Production PAT stored in secret manager (not env files)
• ] PAT uses minimum required scopes (file_content:read, not files:read)
• ] PAT expiry tracked (max 90 days) with rotation reminder
• ] OAuth refresh token flow tested (if using OAuth)
• ] Separate tokens for dev/staging/prod
• ] No tokens in client-side code or git history

Step 2: Error Handling

• ] All HTTP status codes handled (400, 403, 404, 429, 500)
• ] Retry-After header honored on 429 responses
• ] Exponential backoff with jitter for transient errors
• ] Max retry limit to prevent infinite loops
• ] Graceful degradation when Figma is unavailable
• ] Error responses do not leak token values in logs

Step 3: Rate Limiting

• ] Request queue with concurrency control (max 3-5 concurrent)
• ] Batch node IDs in single requests (up to 50 per call)
• ] Response caching for frequently accessed files (TTL: 60-300s)
• ] Rate limit monitor with proactive throttling
• ] No tight loops calling Figma API without delays

Step 4: Monitoring & Health

typescript
// Health check endpoint
async function figmaHealthCheck() {
  const start = Date.now();
  try {
    const res = await fetch('https://api.figma.com/v1/me', {
      headers: { 'X-Figma-Token': process.env.FIGMA_PAT! },
      signal: AbortSignal.timeout(5000),
    });
    return {
      status: res.ok ? 'healthy' : 'degraded',
      latencyMs: Date.now() - start,
      httpStatus: res.status,
    };
  } catch (error) {
    return {
      status: 'unhealthy',
      latencyMs: Date.now() - start,
      error: error instanceof Error ? error.message : 'Unknown',
    };
  }
}

• ] Health endpoint includes Figma connectivity check
• ] Alerts on sustained 429 errors (>5/min)
• ] Alerts on 403 errors (token expiry)
• ] Alerts on response latency >5s (P95)
• ] Dashboard tracks requests/min, error rate, latency

Step 5: Data Handling

• ] Image export URLs treated as temporary (expire after 30 days)
• ] No PII from Figma stored without user consent
• ] File data cached with appropriate TTL
• ] Large file responses streamed, not buffered entirely in memory

Step 6: Webhook Production Setup

• ] HTTPS endpoint (Figma requires TLS)
• ] Passcode verification on every incoming webhook
• ] Idempotency handling for duplicate deliveries
• ] Quick response (200 within 5s) with async processing
• ] Dead letter queue for failed webhook processing

Step 7: Pre-Flight Verification

bash
#!/bin/bash
echo "=== Figma Production Pre-Flight ==="

# 1. Token valid?
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "X-Figma-Token: ${FIGMA_PAT}" \
  https://api.figma.com/v1/me)
echo "Auth: $STATUS (expect 200)"

# 2. File accessible?
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}?depth=1")
echo "File: $STATUS (expect 200)"

# 3. Figma status page
echo -n "Figma Status: "
curl -s https://www.figmastatus.com/api/v2/status.json 2>/dev/null \
  | jq -r '.status.description // "Unable to check"'

echo "=== Pre-flight complete ==="

Output

• All checklist items verified
• Health check endpoint deployed
• Monitoring and alerting configured
• Pre-flight script passing

Error Handling

| Alert | Condition | Severity | Action | |-------|-----------|----------|--------| | Auth Failure | 403 errors > 0 | P1 | Rotate PAT immediately | | Rate Limited | 429 errors > 5/min | P2 | Reduce request rate; check plan tier | | High Latency | P95 > 5000ms | P2 | Check Figma status; add caching | | API Down | 5xx errors > 10/min | P1 | Enable fallback; check status.figma.com |

Examples

Run the Step 7 pre-flight before the go-live cut:

bash
./scripts/figma-preflight.sh

text
✓ FIGMA_PAT present, not in repo (gitleaks clean)
✓ /v1/me → 200 (token valid, acting as design-infra@example.com)
✓ File probe ?depth=1 → 200 in 240ms
✓ 429 handler: Retry-After honored (simulated)
✓ Webhook passcode verification: forged POST → 401
✗ Alerting: no alert rule for figma_api_requests_total{status="429"}
1 failure — fix before ship

Each line maps to a checklist step in this skill (auth → errors → rate limits → monitoring → data → webhooks). A red pre-flight is the checklist telling you which section to reopen — here, Step 4 (references/monitoring-health.md).

Resources

• Figma Status Page
• Figma Rate Limits
• Figma API Scopes

Next Steps

For version upgrades, see figma-upgrade-migration.