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

Resources

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

Next Steps

For version upgrades, see figma-upgrade-migration.