​

Troubleshooting

​

Authentication Issues

​

”Invalid API Key” (401)

1. Verify the key format
   • Live keys start with pk_live_
   • Test keys start with pk_test_
2. Check for extra characters
   Copy

   # Wrong - has quotes
   PICTIFY_API_KEY="pk_live_..."
   
   # Correct - no quotes in shell
   PICTIFY_API_KEY=pk_live_...
   
3. Verify the key isn’t revoked
   • Check in Dashboard > Settings > API Keys
4. Ensure correct environment
   • Test keys don’t work in production mode

​

”Missing Authorization” (401)

# Make sure header is correct
curl https://api.pictify.io/image \
  -H "Authorization: Bearer pk_live_your_key"  # ✅ Correct

# Common mistakes:
-H "Authorization: pk_live_your_key"           # ❌ Missing "Bearer"
-H "Api-Key: pk_live_your_key"                 # ❌ Wrong header name

​

Rendering Issues

​

Blank or White Images

1. Check HTML has visible content
   Copy

   <!-- Wrong - no dimensions -->
   <div>Hello</div>
   
   <!-- Correct - explicit dimensions -->
   <div style="width: 1200px; height: 630px; background: #fff;">
     Hello
   </div>
   
2. Ensure content is within viewport
   • Content outside the width/height won’t be captured
3. Check for transparent backgrounds
   Copy

   // If using transparent: true, background may be invisible
   { transparent: true }  // Background won't show
   

​

Missing Fonts

1. Use web fonts with @import
   Copy

   <style>
     @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap');
     body { font-family: 'Inter', sans-serif; }
   </style>
   
2. Use web-safe fonts as fallback
   Copy

   font-family: 'Inter', Arial, sans-serif;
   
3. Wait for font loading
   Copy

   {
     waitForTimeout: 1000  // Give fonts time to load
   }
   

​

CSS Not Applied

1. Use inline styles for reliability
   Copy

   <!-- More reliable -->
   <div style="color: red; font-size: 24px;">Hello</div>
   
2. Check for unsupported CSS
   • Some advanced CSS features may not render correctly
   • Test complex layouts in browser first
3. Avoid external stylesheets on slow domains
   • External CSS must load before rendering

​

Images Not Loading

1. Use absolute URLs
   Copy

   <!-- Wrong -->
   <img src="/images/logo.png" />
   
   <!-- Correct -->
   <img src="https://yoursite.com/images/logo.png" />
   
2. Verify URL is accessible
   • Images must be publicly accessible
   • Check for CORS issues
3. Use waitForSelector
   Copy

   {
     waitForSelector: 'img[src*="logo"]',
     waitForTimeout: 2000
   }
   

​

Timeout Errors

1. Simplify the template
   • Remove complex gradients, shadows
   • Reduce number of elements
2. Optimize images
   • Use smaller image files
   • Compress before including
3. Reduce external resources
   • Minimize external CSS/JS
   • Self-host critical resources

​

Template Issues

​

Variables Not Interpolating

1. Check variable syntax
   Copy

   ✅ {{title}}
   ❌ {{ title }}  // Spaces may cause issues
   ❌ {title}      // Single braces don't work
   
2. Verify variable is provided
   Copy

   // Make sure all variables are passed
   await pictify.templates.render('tmpl_id', {
     variables: {
       title: 'Hello'  // Must match {{title}}
     }
   });
   
3. Check for typos
   • Variable names are case-sensitive
   • {{Title}} !== {{title}}

​

Expression Errors

1. Test expressions separately
   Copy

   curl -X POST https://api.pictify.io/templates/expression/test \
     -H "Authorization: Bearer $API_KEY" \
     -d '{
       "expression": "currency(price, 'USD')",
       "variables": {"price": 99.99}
     }'
   
2. Check function syntax
   Copy

   ✅ {{currency(price, 'USD')}}
   ❌ {{currency(price, USD)}}  // String needs quotes
   
3. Ensure variables exist
   • Undefined variables cause expression errors

​

Rate Limiting

​

”Rate Limit Exceeded” (429)

1. Check headers for limit info
   Copy

   X-RateLimit-Limit: 60
   X-RateLimit-Remaining: 0
   X-RateLimit-Reset: 1706515320
   Retry-After: 45
   
2. Implement exponential backoff
   Copy

   async function withRetry(fn, maxRetries = 3) {
     for (let i = 0; i < maxRetries; i++) {
       try {
         return await fn();
       } catch (error) {
         if (error.status === 429) {
           const delay = error.retryAfter || Math.pow(2, i) * 1000;
           await sleep(delay);
           continue;
         }
         throw error;
       }
     }
   }
   
3. Use batch API for bulk operations
   • Single batch request vs. many individual requests
4. Consider upgrading plan
   • Higher tiers have higher limits

​

Webhook Issues

​

Webhooks Not Received

1. Verify endpoint is accessible
   Copy

   curl -X POST https://yoursite.com/webhooks/pictify \
     -H "Content-Type: application/json" \
     -d '{"test": true}'
   
2. Check firewall/security rules
   • Allow incoming requests from Pictify IPs
   • Ensure HTTPS certificate is valid
3. Verify subscription is active
   • Check in Dashboard > Settings > Webhooks
   • Status should be “active”

​

Signature Verification Failing

1. Use raw body for verification
   Copy

   // ❌ Wrong
   const payload = JSON.stringify(req.body);
   
   // ✅ Correct
   const payload = req.body.toString();  // Raw body
   
2. Check timestamp tolerance
   • Default is 5 minutes
   • Ensure server clock is synced
3. Verify using correct secret
   • Each subscription has a unique secret
   • Secret is only shown at creation

​

SDK Issues

​

Module Not Found

# Ensure package is installed
npm install @pictify/sdk

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

​

TypeScript Errors

1. Update TypeScript
   Copy

   npm install typescript@latest
   
2. Check tsconfig.json
   Copy

   {
     "compilerOptions": {
       "moduleResolution": "node",
       "esModuleInterop": true
     }
   }
   

​

Still Need Help?

1. Check the status page: status.pictify.io
2. Search existing issues: GitHub Issues
3. Contact support: support@pictify.io

• API endpoint and method
• Request payload (without API key)
• Error response
• SDK version (if applicable)