canva-known-pitfalls

# Canva Known Pitfalls ## Overview Common mistakes when integrating with the Canva Connect API. Each pitfall includes the anti-pattern, why it fails, and the correct approach with real API endpoints. ## Pitfall #1: Not Handling Token Expiry ```typescript // WRONG — token expires after ~4 hours, then all calls fail const token = await getTokenOnce(); // ... 5 hours later ... await canvaAPI('/designs', token); // 401 Unauthorized // RIGHT — auto-refresh before expiry class CanvaClient { async request(path: string, init?: RequestInit) { if (Date.now() > this.tokens.expiresAt - 300_000) { await this.refreshToken(); // Refresh 5 min before expiry } // ... make request } } ``` ## Pitfall #2: Reusing Refresh Tokens ```typescript // WRONG — refresh tokens are single-use in Canva's OAuth const tokens = await refreshAccessToken(storedRefreshToken); // Later, using the SAME refresh token again: const tokens2 = await refreshAccessToken(storedRefreshToken); // FAILS // RIGHT — always store the new refresh token immediately const tokens = await refreshAccessToken(storedRefreshToken); await db.saveTokens(userId, { accessToken: tokens.access_token, refreshToken: tokens.refresh_token, // NEW token — store it! expiresAt: Date.now() + tokens.expires_in * 1000, }); ``` ## Pitfall #3: Synchronous Export Polling in Request Handler ```typescript // WRONG — user waits 5-30 seconds while export completes app.post('/api/export', async (req, res) => { const { job...