Lucidchart common errors

Lucidchart Common Errors

Overview

Lucidchart's API enables programmatic diagram creation, document management, shape manipulation, and team collaboration workflows. Common integration errors include OAuth token expiration during long-running batch operations, document lock conflicts when multiple users edit simultaneously, and shape API 422 errors from invalid geometry or missing parent references. The OAuth token refresh flow is the most common stumbling block -- access tokens expire after 60 minutes, and batch operations that exceed this window fail mid-run. This reference covers authentication, document lifecycle, and shape-level validation issues for the Lucid developer platform.

Error Reference

Code	Message	Cause	Fix
401	Token expired	OAuth2 access token expired	Use refresh token to obtain new access token
403	Insufficient scopes	OAuth app missing required permission scopes	Re-authorize with lucidchart.document.content and needed scopes
404	Document not found	Invalid document ID or user lacks access	Verify document ID and that API user has viewer/editor role
409	Document locked	Another user is actively editing	Wait for lock release or use force-unlock with admin privileges
422	Invalid shape data	Shape position/size out of bounds or missing parent	Validate x/y/width/height > 0; ensure parent page exists
422	Invalid connection	Source or target shape ID does not exist	Create shapes before connecting them; verify shape IDs
429	Rate limited	Exceeded 100 requests/minute	Implement exponential backoff; batch shape operations
500	Export failed	PDF/PNG export timed out on complex diagram	Reduce page count or simplify shapes before export

Error Handler

interface LucidchartError {
  code: number;
  message: string;
  category: "auth" | "rate_limit" | "validation" | "conflict";
}

function classifyLucidchartError(status: number, body: string): LucidchartError {
  if (status === 401 || status === 403) {
    return { code: status, message: body, category: "auth" };
  }
  if (status === 429) {
    return { code: 429, message: "Rate limited", category: "rate_limit" };
  }
  if (status === 409) {
    return { code: 409, message: body, category: "conflict" };
  }
  return { code: status, message: body, category: "validation" };
}

Debugging Guide

Authentication Errors

Lucidchart uses OAuth2 with access and refresh tokens. Access tokens expire after 60 minutes. Always implement token refresh logic. A 403 typically means missing OAuth scopes rather than invalid credentials -- check the scopes parameter in your authorization URL against the API endpoints you are calling.

Rate Limit Errors

The API enforces 100 requests/minute per OAuth token. Shape creation in bulk should use batch endpoints. Export operations (PDF, PNG) count against the same limit. Use Retry-After header and implement exponential backoff starting at 1 second.

Validation Errors

Shape creation requires valid x, y, width, and height values (all positive integers). Zero or negative values return 422. Connections require both source and target shape IDs to exist on the same page -- cross-page connections are not supported. Page references must use valid page IDs from the document; list pages first before creating shapes.

Error Handling

Scenario	Pattern	Recovery
OAuth token expired mid-batch	401 after N successful calls	Refresh token, resume from last successful operation
Document locked by teammate	409 on write operations	Poll lock status every 10s; notify user if persistent
Shape API 422	Invalid geometry values	Validate all shape coordinates are positive before API call
Export timeout on large diagram	500 on PDF/PNG export	Export individual pages instead of full document
Connection fails between shapes	Target shape not yet created	Create all shapes first, then create connections

Quick Diagnostic

# Verify OAuth token validity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $LUCID_ACCESS_TOKEN" \
  https://api.lucid.co/v1/users/me

Resources

• Lucid Developer Docs
• Lucid OAuth2 Guide

Next Steps

See lucidchart-debug-bundle.