Troubleshooting

Common issues and solutions when using the Canvelete (opens in a new tab) rendering API.

Authentication Errors

"Invalid API key" (401)

Causes:

API key is incorrect or expired
Missing Bearer prefix in Authorization header
Key was revoked

Solutions:

Verify your key at Settings → API Keys (opens in a new tab)
Ensure header format: Authorization: Bearer YOUR_KEY
Generate a new key if needed

# Correct format
curl -H "Authorization: Bearer cvt_your_api_key" ...
 
# ❌ Wrong: Missing Bearer
curl -H "Authorization: cvt_your_api_key" ...

"Forbidden" (403)

Causes:

API key lacks required permissions
Accessing another user's resources
Feature not available on your plan

Solutions:

Check key permissions in dashboard
Verify you own the design/template
Review your subscription plan (opens in a new tab)

Rendering Errors

"Design not found" (404)

Causes:

Incorrect design ID
Design was deleted
Design is in another account

Solutions:

Verify design ID in your dashboard (opens in a new tab)
Check the URL when editing: /editor/design_xxx
Ensure design is saved (not just a draft)

"Render timeout"

Causes:

Design is too complex
Large images in design
Server overload

Solutions:

Reduce element count
Compress/resize images
Lower output quality
Use async rendering with webhooks

# Use async for complex designs
result = client.render.create(
    design_id="complex_design",
    async_mode=True,
    webhook="https://your-app.com/webhook"
)

"Invalid dynamic data"

Causes:

Variable name mismatch
Wrong data type
Missing required variables

Solutions:

Check variable names match design placeholders
Verify data types (string, number, URL)
Test in the editor's preview mode first

# ❌ Wrong: Variable name mismatch
dynamic_data = {"userName": "John"}  # Design uses {{name}}
 
# ✅ Correct: Match design variables
dynamic_data = {"name": "John"}

"Image URL not accessible"

Causes:

URL is private/requires auth
URL is blocked by CORS
URL is invalid or broken

Solutions:

Use publicly accessible URLs
Upload images to Canvelete asset library
Use CDN URLs for external images

# ✅ Use Canvelete assets
asset = client.assets.upload("image.png")
dynamic_data = {"image": asset["url"]}
 
# ✅ Or use public CDN URLs
dynamic_data = {"image": "https://cdn.example.com/image.png"}

Rate Limiting

"Too many requests" (429)

Causes:

Exceeded requests per minute
Exceeded daily/monthly limits

Solutions:

Implement exponential backoff
Use batch API for multiple renders
Upgrade your plan for higher limits

import time
from canvelete.exceptions import RateLimitError
 
def render_with_retry(config, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.render.create(**config)
        except RateLimitError as e:
            if attempt < max_retries - 1:
                time.sleep(e.retry_after or 2 ** attempt)
            else:
                raise

Output Quality Issues

Blurry or pixelated output

Causes:

Low quality setting
Small source images
Wrong scale factor

Solutions:

Increase quality (80-95 recommended)
Use higher resolution source images
Adjust scale factor

result = client.render.create(
    design_id="design_123",
    format="png",
    quality=95,  # Higher quality
    scale=2.0    # 2x resolution
)

Colors look different

Causes:

Color space conversion
JPEG compression
Monitor calibration

Solutions:

Use PNG for accurate colors
Increase JPEG quality
Use hex colors consistently

Fonts not rendering correctly

Causes:

Font not available
Font weight mismatch
Special characters not supported

Solutions:

Use fonts from the available fonts list
Upload custom fonts to asset library
Test with preview before rendering

Webhook Issues

Webhooks not received

Causes:

Endpoint not accessible
Firewall blocking requests
Endpoint returning errors

Solutions:

Verify endpoint is publicly accessible
Check firewall/security rules
Ensure endpoint returns 200 status
Test with webhook testing tools (opens in a new tab)

Invalid webhook signature

Causes:

Wrong signing secret
Payload modified
Encoding issues

Solutions:

Verify signing secret from dashboard
Use raw request body for verification
Check encoding (UTF-8)

import hmac
import hashlib
 
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,  # Use raw bytes
        hashlib.sha256
    ).hexdigest()
    return f"sha256={expected}" == signature

Debug Mode

Enable debug mode for detailed error information:

client = CanveleteClient(
    api_key="YOUR_KEY",
    debug=True  # Enable debug logging
)

Or in API requests:

{
  "format": "png",
  "debug": true,
  "dynamicData": { ... }
}

Getting Help

If issues persist:

Check status: status.canvelete.com (opens in a new tab)
Search docs: Use the search bar above
Community: Discord (opens in a new tab)
Support: support@canvelete.com

When contacting support, include:

Request ID (from error response)
Design ID
API request/response
Expected vs actual behavior

Performance Optimization Batch Processing