figma-prod-checklist

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

// 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

#!/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

Resources

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

Next Steps

For version upgrades, see figma-upgrade-migration.