From figma-pack
Diagnoses and fixes common Figma REST API and Plugin API errors including 400/403/404/429/500 HTTP issues, token problems, rate limits, and file access errors.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin figma-packThis skill is limited to using the following tools:
Quick reference for the most common Figma REST API and Plugin API errors, with exact error messages and working solutions.
Triages and mitigates Figma API incidents like outages, 403 auth failures, 429 rate limits using curl scripts, decision trees, and rotation steps.
Mandatory prerequisite skill for `use_figma` tool calls to execute JS in Figma files. Enables node create/edit/delete, variables/tokens setup, component building, auto-layout changes, property binding, and programmatic file inspection.
Loads mandatory prerequisite context before every use_figma tool call for Figma writes or JS-executed reads like node edits, variable setup, component building, or file inspection.
Share bugs, ideas, or general feedback.
Quick reference for the most common Figma REST API and Plugin API errors, with exact error messages and working solutions.
| Status | Error | Cause | Solution |
|---|---|---|---|
| 400 | Bad Request | Malformed request, invalid node IDs | Verify node ID format (pageId:nodeId, e.g., 0:1) |
| 403 | Forbidden | Invalid token, wrong scopes, no file access | Regenerate PAT with correct scopes; verify file sharing |
| 404 | Not Found | Wrong file key, deleted file, wrong endpoint | Check file key from URL; verify file exists |
| 429 | Rate Limited | Too many requests | Read Retry-After header; implement backoff |
| 500 | Internal Server Error | Figma server issue | Retry with exponential backoff; check status.figma.com |
# Test your token
curl -s -o /dev/null -w "%{http_code}" \
-H "X-Figma-Token: ${FIGMA_PAT}" \
https://api.figma.com/v1/me
# 200 = token valid, 403 = invalid/expired
# Check what scopes your request needs
# file_content:read -> GET /v1/files/:key
# file_comments:read -> GET /v1/files/:key/comments
# file_variables:read -> GET /v1/files/:key/variables/local
# webhooks:write -> POST /v2/webhooks
Common 403 causes:
file_content:read but calling comments endpoint)// Figma returns these headers on 429:
// Retry-After: <seconds> -- wait this long before retrying
// X-Figma-Rate-Limit-Type: <type> -- "low" or "high" tier
// X-Figma-Plan-Tier: <plan> -- your plan level
async function handleRateLimit(response: Response) {
if (response.status === 429) {
const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
const limitType = response.headers.get('X-Figma-Rate-Limit-Type');
console.warn(`Rate limited (${limitType}). Retrying in ${retryAfter}s`);
await new Promise(r => setTimeout(r, retryAfter * 1000));
return true; // signal to retry
}
return false;
}
# Verify your file key is correct
# URL format: https://www.figma.com/design/<FILE_KEY>/<file-name>
# The file key is the string between /design/ and the next /
# Test the file key
curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
"https://api.figma.com/v1/files/${FIGMA_FILE_KEY}" \
| jq '.name // "FILE NOT FOUND"'
null// GET /v1/images/:key returns null for nodes that cannot render
const images = await exportImages(['0:1', '0:2']);
for (const [nodeId, url] of Object.entries(images)) {
if (url === null) {
// Node failed to render. Common causes:
// - Node is invisible (visibility: false)
// - Node has 0% opacity
// - Node ID does not exist in the file
// - Node has no visual content (e.g., an empty frame)
console.error(`Failed to render node ${nodeId}`);
}
}
| Error | Context | Cause | Solution |
|---|---|---|---|
figma is not defined | Node.js / browser | Running plugin code outside Figma sandbox | Plugin code only runs inside Figma desktop app |
Cannot read property of undefined | Plugin | Accessing deleted node reference | Re-query node: figma.getNodeById(id) |
Plugin timed out | Plugin | Operation took too long | Use figma.commitUndo() and batch operations |
Quota exceeded | Plugin | Too many nodes created | Limit to ~5000 nodes per operation |
Permission denied | Plugin | Missing manifest.json permission | Add required permission to permissions array |
#!/bin/bash
echo "=== Figma API Diagnostics ==="
# 1. Check Figma service status
echo -n "Figma Status: "
curl -s -o /dev/null -w "%{http_code}" https://www.figma.com && echo " OK" || echo " DOWN"
# 2. Validate token
echo -n "Token Valid: "
curl -s -o /dev/null -w "%{http_code}" \
-H "X-Figma-Token: ${FIGMA_PAT}" \
https://api.figma.com/v1/me
# 3. Check file access
echo -n "File Access: "
curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
"https://api.figma.com/v1/files/${FIGMA_FILE_KEY}" \
| jq -r '.name // "FAILED"'
# 4. Check env vars
echo "FIGMA_PAT: ${FIGMA_PAT:+SET (${#FIGMA_PAT} chars)}"
echo "FIGMA_FILE_KEY: ${FIGMA_FILE_KEY:-NOT SET}"
function diagnoseFigmaError(status: number, body: string): string {
switch (status) {
case 403: return 'Auth failed. Check: (1) PAT not expired (2) correct scopes (3) file shared with you';
case 404: return 'Not found. Check: (1) file key from URL (2) file not deleted (3) node IDs valid';
case 429: return 'Rate limited. Implement exponential backoff with Retry-After header';
case 500: return 'Figma server error. Check status.figma.com and retry with backoff';
default: return `Unexpected ${status}: ${body}`;
}
}
For comprehensive debugging, see figma-debug-bundle.