Troubleshooting Sync Failures

When a sync job fails, this guide helps you diagnose the root cause and fix it quickly. We'll cover all common failure modes and their solutions.

Quick Diagnosis Flowchart

Start here to quickly identify your issue:

Is the connection status "Backend not reachable"?
├─ YES → See "Backend Connectivity Issues"
└─ NO → Continue

Does the error message contain "Invalid Vimeo URL"?
├─ YES → See "Invalid URL Errors"
└─ NO → Continue

Does the error message contain "Authentication"?
├─ YES → See "Authentication Errors"
└─ NO → Continue

Does the error message contain "Rate limit"?
├─ YES → See "Rate Limit Errors"
└─ NO → Continue

Does the error message contain "Network error"?
├─ YES → See "Network Errors"
└─ NO → See "Unknown Errors"

Authentication Errors

Error: "Authentication failed: Invalid API token"

Full Error Message:

Authentication failed: Invalid API token
Status code: 401 Unauthorized

Cause: The Vimeo API token is invalid, expired, or revoked.

Solutions:

Solution 1: Verify Token Validity

Test the token manually:

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" https://api.vimeo.com/me

Expected Response (Valid Token):

{
  "uri": "/users/123456789",
  "name": "Your Name",
  ...
}

Error Response (Invalid Token):

{
  "error": "Invalid token",
  "error_code": 8003
}

Solution 2: Check Token Scopes

Tokens must have these scopes:

public — Access to public videos
private — Access to private videos (if importing private content)
video_files — Access to video metadata and transcripts

How to Check:

Go to Vimeo Developer Apps
Click on your app
Go to "Authentication" tab
Verify the Personal Access Token has all required scopes

Solution 3: Regenerate Token

If the token is expired or revoked:

Go to Vimeo Developer Apps
Click on your app
Go to "Authentication" tab
Click "Generate New Token"
Select scopes: public, private, video_files
Copy the new token
Update your backend environment variable:
- Cloud Hosted: Contact your administrator
- Self-Hosted: Update .env file: VIMEO_ACCESS_TOKEN=new_token_here
Restart the application

Solution 4: Check Account Status

If regenerating the token doesn't help:

Log into your Vimeo account at https://vimeo.com
Check if your account is in good standing (no suspensions or restrictions)
Verify your app hasn't been suspended or deleted

If Account Is Suspended: Contact Vimeo support to resolve account issues.

Error: "Forbidden: Access denied to this resource"

Full Error Message:

Forbidden: Access denied to this resource
Status code: 403 Forbidden

Cause: The token is valid, but lacks permissions to access the requested resource.

Common Scenarios:

Scenario 1: Private Content

You're trying to import a private video, showcase, or album, but the token doesn't have access.

Solution:

Ensure the token belongs to the same Vimeo account that owns the private content
Or, ensure the content is set to "Public" or "Unlisted" on Vimeo

Scenario 2: Missing Scopes

The token is missing required scopes (e.g., private scope for private videos).

Solution:

Regenerate the token with all required scopes: public, private, video_files

Scenario 3: Content Was Deleted

The video or collection was deleted from Vimeo after you saved the URL.

Solution:

Verify the URL exists by opening it in a browser
If it's gone, remove it from your import list

Invalid URL Errors

Error: "Invalid Vimeo URL: Unsupported format"

Full Error Message:

Invalid Vimeo URL: Unsupported format
Provided URL: https://example.com/video

Cause: The URL doesn't match any of the five supported Vimeo URL patterns.

Supported Patterns:

https://vimeo.com/user{userid}
https://vimeo.com/user{userid}/albums
https://vimeo.com/user{userid}/videos
https://vimeo.com/user{userid}/collections
https://vimeo.com/showcase/{showcaseid}

Solutions:

Solution 1: Check for Typos

Common typos:

vimoe.com instead of vimeo.com
user/123 instead of user123
collection instead of collections (singular vs plural)

Solution 2: Remove Query Parameters

Some Vimeo URLs include tracking parameters:

❌ https://vimeo.com/showcase/11708791?h=abc123def
✅ https://vimeo.com/showcase/11708791

Solution: Remove everything after the ?:

https://vimeo.com/showcase/11708791

Solution 3: Use Public URL, Not Admin URL

Admin URL (Wrong):

❌ https://vimeo.com/manage/showcases/11708791
❌ https://vimeo.com/manage/videos/987654321

Public URL (Correct):

✅ https://vimeo.com/showcase/11708791
✅ https://vimeo.com/987654321

How to Get Public URL:

Click "View Public Page" link in your Vimeo admin panel
Copy URL from the public-facing page

Error: "Invalid Vimeo URL: Resource not found"

Full Error Message:

Invalid Vimeo URL: Resource not found
Provided URL: https://vimeo.com/showcase/99999999
Status code: 404 Not Found

Cause: The URL format is correct, but the resource (showcase, user, video) doesn't exist on Vimeo.

Solutions:

Solution 1: Verify URL Exists

Open the URL in a browser:

If you see the showcase/video → URL is valid; backend token may lack access
If you see "Page not found" → URL is incorrect or resource was deleted

Solution 2: Check Privacy Settings

Private Content: If the showcase/video is private, you must:

Use a token from the account that owns it
Or, change the privacy setting to "Public" or "Unlisted" on Vimeo

How to Check Privacy:

Log into Vimeo as the content owner
Go to the showcase/video settings
Check "Privacy" setting
Change to "Public" or "Unlisted" if needed

Solution 3: Check for Deleted Content

If the URL previously worked but now shows 404:

The video owner may have deleted the content
The showcase may have been unpublished
The user account may have been suspended

Solution: Verify with the content owner that the URL is still valid.

Rate Limit Errors

Error: "Rate limit exceeded"

Full Error Message:

Rate limit exceeded
Status code: 429 Too Many Requests
Retry after: 600 seconds

Cause: You've exceeded Vimeo's API rate limit of 600 calls per 10 minutes (or 3600 calls per 10 minutes with Token Pool).

Solutions:

Solution 1: Wait and Retry

Immediate Solution:

Wait 10 minutes for the rate limit window to reset
Click "Retry Import" button in the dashboard

Why This Happens:

You're syncing large showcases (100+ videos)
Multiple concurrent syncs are running
Previous sync jobs haven't finished cooling down

Solution 2: Enable Token Pool (6x Capacity)

Long-Term Solution: Set up Token Pool for 3600 calls/10min capacity (6x increase).

See: How to Set Up Token Pool

Benefits:

6x faster sync speeds
Automatic failover when one token hits rate limit
Supports syncing 500+ videos without pausing

Solution 3: Stagger Sync Jobs

If Running Multiple Syncs:

Space them out by 5-10 minutes
Don't start 5 showcases simultaneously

Scheduling Example:

9:00 AM — Start Sync Job 1
9:10 AM — Start Sync Job 2
9:20 AM — Start Sync Job 3

Why This Helps: Gives each sync job access to the full 600 calls/10min capacity.

Solution 4: Use Incremental Sync Mode

On Repeat Imports:

First import: Use Full Sync (imports everything)
Subsequent imports: Use Incremental Sync (only fetches changes)

Why This Helps: Incremental Sync skips unchanged videos, dramatically reducing API calls.

Example:

Full Sync of 100 videos: 200 API calls
Incremental Sync (3 new videos): 10 API calls (95% reduction)

See Your First Complete Sync for details.

Error: "All tokens are in cooldown"

Full Error Message (Token Pool Only):

RateLimitError: All tokens are in cooldown
Retry after: 347 seconds

Cause: You're using Token Pool, but all 6 tokens hit their rate limits simultaneously.

Why This Happens:

You're making 3600+ API calls in less than 10 minutes (exceeding even 6x capacity)
Very large showcases (500+ videos) with many transcripts
Multiple users syncing concurrently

Solutions:

Solution 1: Wait for Token Recovery

Tokens auto-recover after 10 minutes of cooldown.

Check cooldown status:

# Access Prometheus metrics
curl http://localhost:9091/metrics | grep vimeo_token_pool_health_state

Look for:

vimeo_token_pool_health_state{token_id="token1@..."} 1

0 = FAILED (permanently down)
1 = COOLDOWN (recovers in under 10 min)
2 = HEALTHY (ready to use)

When all tokens show 2 (HEALTHY), retry your sync.

Solution 2: Add More Tokens

Increase capacity to 12 or 18 tokens:

12 Tokens = 7200 calls/10min 18 Tokens = 10,800 calls/10min

See: How to Set Up Token Pool for token generation instructions.

Solution 3: Reduce Concurrency

If multiple users/jobs are syncing:

Limit to 2-3 concurrent syncs
Queue additional syncs to start after current ones finish

Backend Configuration (For Administrators):

# In .env file
SYNC_CONCURRENCY=3  # Max 3 concurrent sync jobs

Network Errors

Error: "Network error: Could not connect to Vimeo API"

Full Error Message:

Network error: Could not connect to Vimeo API
Error: Connection timeout after 30 seconds

Cause: The backend server cannot reach Vimeo's API due to network issues.

Solutions:

Solution 1: Check Internet Connectivity

On the backend server:

# Ping Vimeo
ping api.vimeo.com

# Test HTTPS connectivity
curl -I https://api.vimeo.com

Expected Response:

HTTP/2 200

If curl fails:

Backend server has no internet access
Firewall is blocking outbound HTTPS traffic
DNS resolution is failing

Solution 2: Check Vimeo Status

Visit: https://status.vimeo.com

If Vimeo reports outages:

Wait for Vimeo to resolve the issue
Retry your sync after the outage is resolved

Monitor Vimeo Status:

# Subscribe to Vimeo status updates
https://status.vimeo.com/subscribe

Solution 3: Check Firewall Rules

If behind a corporate firewall:

Ensure outbound HTTPS (port 443) traffic to api.vimeo.com is allowed
Whitelist Vimeo's IP ranges (contact Vimeo support for current ranges)

Test with curl:

curl -v https://api.vimeo.com/me

Look for:

Connection refused → Firewall blocking
Connection timeout → Firewall dropping packets
SSL certificate error → HTTPS inspection interfering

Solution 4: Increase Timeout

If on slow network:

Backend Configuration (For Administrators):

# In .env file
HTTP_TIMEOUT_CONNECT=30   # Connection timeout (seconds)
HTTP_TIMEOUT_READ=60      # Read timeout (seconds)

Restart application after changes.

Error: "SSL certificate verification failed"

Full Error Message:

Network error: SSL certificate verification failed
Error: unable to get local issuer certificate

Cause: The backend server cannot verify Vimeo's SSL certificate.

Solutions:

Solution 1: Update CA Certificates

On the backend server:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install ca-certificates
sudo update-ca-certificates

RHEL/CentOS:

sudo yum update ca-certificates

Docker (Rebuild Image):

docker compose build --no-cache
docker compose up -d

Solution 2: Check System Time

SSL certificate validation requires accurate system time.

Check current time:

date

If time is wrong, sync with NTP:

sudo ntpdate pool.ntp.org

Or enable NTP service:

sudo systemctl enable systemd-timesyncd
sudo systemctl start systemd-timesyncd

Solution 3: Disable SSL Verification (Not Recommended)

Only for testing/debugging:

Backend Configuration (For Administrators):

# In .env file
HTTP_VERIFY_SSL=false   # WARNING: Security risk!

Do NOT use in production. This makes your connection vulnerable to man-in-the-middle attacks.

Backend Connectivity Issues

Dashboard Shows "Backend not reachable"

Symptoms:

Red connection status indicator in dashboard header
Cannot start new syncs
"Recent Jobs" sidebar is empty or outdated

Cause: Dashboard cannot reach the backend API.

Solutions:

Solution 1: Check Backend Is Running

If Using Docker Compose:

docker compose ps

Expected Output:

NAME                     STATUS
vimeo-connector          Up 5 minutes

If status is "Exited":

# View logs to see why it crashed
docker compose logs vimeo-connector

# Restart
docker compose up -d

Solution 2: Verify API Endpoint

Check backend health endpoint:

curl http://localhost:8000/api/v1/health

Expected Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-10-17T14:22:10Z"
}

If curl fails:

Backend is not listening on port 8000
Backend crashed or failed to start
Port is already in use by another application

Solution 3: Check Dashboard Configuration

Dashboard must point to correct backend URL.

If Self-Hosting:

Check dashboard's config.js or environment variable for API URL
Ensure it matches where the backend is running

Example:

// config.js
export const API_BASE_URL = "http://localhost:8000/api/v1";

Solution 4: Check Network/Firewall

If backend and dashboard are on different servers:

Test connectivity from dashboard server to backend:

curl http://backend-server:8000/api/v1/health

If this fails:

Firewall is blocking port 8000
Network route between servers doesn't exist
Backend is only listening on localhost (127.0.0.1), not all interfaces (0.0.0.0)

Solution (Backend Configuration):

# Ensure backend binds to all interfaces
# In .env file
HOST=0.0.0.0
PORT=8000

Unknown Errors

Error: "Unknown error occurred"

Full Error Message:

Unknown error occurred
Error details: [error message from backend]

Cause: An unexpected error that doesn't match common failure patterns.

Solutions:

Solution 1: Check Backend Logs

If Using Docker Compose:

docker compose logs vimeo-connector --tail=100

If Running Natively:

tail -f /var/log/vimeo-connector/app.log

Look for:

Python stack traces (indicate code bugs)
"ERROR" or "CRITICAL" log level messages
Specific error messages that provide more context

Solution 2: Check System Resources

Backend may be out of memory or disk space:

Check memory:

free -h

Check disk space:

df -h

If low on resources:

Restart the backend to clear memory leaks
Free up disk space (delete old logs, temporary files)
Upgrade server resources (more RAM, storage)

Solution 3: Reproduce with Minimal Example

Isolate the issue:

Try syncing a different, smaller URL
If that works, the issue is specific to the original URL (possibly malformed data from Vimeo)
If that also fails, the issue is systemic (backend configuration or infrastructure problem)

Solution 4: Report the Issue

If you cannot resolve the issue:

Collect diagnostic information:
- Full error message from dashboard
- Backend logs (docker compose logs vimeo-connector)
- The Vimeo URL you were trying to sync
- System information (OS, Docker version, etc.)
Open a GitHub issue:
- Repository: github.com/adorosario/customgpt-vimeo-data-connector-poc
- Include all diagnostic information
- Tag with bug label

Partial Failures

Some Videos in a Sync Job Failed

Symptoms:

Sync completes with "Completed" status
Results show "Added: 50" but you expected 100
Backend logs show errors for specific videos

Cause: Individual videos failed to import (e.g., transcript download error) but the overall job continued.

Solutions:

Solution 1: Check Backend Logs for Failed Videos

Search logs for errors:

docker compose logs vimeo-connector | grep -i "error.*video"

Example error:

[error] Failed to download transcript for video_id=987654321 error=timeout

Solution 2: Retry with Full Sync

Force re-import of all videos:

Paste the same URL
Select "Full Sync" mode
Click "Import Collection"

This will retry failed videos.

Solution 3: Manually Inspect Failed Videos

Check if failed videos are accessible:

# Replace with actual video ID from logs
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.vimeo.com/videos/987654321

If response is 404 or 403:

Video is private or deleted
Expected that it failed to import

If response is 200:

Video exists and is accessible
Failure was transient (network issue, timeout)
Retry will likely succeed

Prevention Strategies

Best Practices to Avoid Failures

Use Auto Sync Mode
- Automatically chooses Full or Incremental based on history
- Reduces risk of user error (e.g., using Incremental on first import)
Enable Token Pool
- Prevents rate limit errors
- Provides automatic failover
- See How to Set Up Token Pool
Monitor Backend Health
- Set up alerts for:
  - Backend down (no response on health endpoint)
  - High error rate (over 5% failed requests)
  - Rate limit warnings (approaching 600 calls/10min)
- Use Prometheus + Grafana for monitoring
Keep Tokens Fresh
- Rotate API tokens every 90 days
- Monitor token health metrics
- Test tokens periodically:
```
curl -H "Authorization: Bearer TOKEN" https://api.vimeo.com/me
```
Test with Small Collections First
- Before syncing a 500-video showcase, test with a 5-video showcase
- Verify token permissions and connectivity
- Ensure backend has sufficient resources
Schedule Large Syncs During Off-Hours
- Avoids competing with other users for API capacity
- Reduces load on backend server

Diagnostic Checklist

Before asking for help, verify:

Backend is running (docker compose ps shows "Up")
Dashboard connection status is green ("Connected")
Vimeo API token is valid (test with curl)
Vimeo URL is correct format and accessible in browser
Backend logs show no critical errors
System has sufficient resources (memory, disk space)
Vimeo status page shows no outages
Firewall allows outbound HTTPS traffic

Getting Help

If you've tried all solutions and still have issues:

GitHub Issues:

Repository: github.com/adorosario/customgpt-vimeo-data-connector-poc
Include: Full error message, backend logs, Vimeo URL (if public), system info

Vimeo API Support:

For API-specific issues: developer.vimeo.com/help

Community:

Discussions tab on GitHub repository

Optimize Performance:

Understand the System:

API Reference:

REST API Overview

Quick Diagnosis Flowchart​

Authentication Errors​

Error: "Authentication failed: Invalid API token"​

Solution 1: Verify Token Validity​

Solution 2: Check Token Scopes​

Solution 3: Regenerate Token​

Solution 4: Check Account Status​

Error: "Forbidden: Access denied to this resource"​

Scenario 1: Private Content​

Scenario 2: Missing Scopes​

Scenario 3: Content Was Deleted​

Invalid URL Errors​

Error: "Invalid Vimeo URL: Unsupported format"​

Solution 1: Check for Typos​

Solution 2: Remove Query Parameters​

Solution 3: Use Public URL, Not Admin URL​

Error: "Invalid Vimeo URL: Resource not found"​

Solution 1: Verify URL Exists​

Solution 2: Check Privacy Settings​

Solution 3: Check for Deleted Content​

Rate Limit Errors​

Error: "Rate limit exceeded"​

Solution 1: Wait and Retry​

Solution 2: Enable Token Pool (6x Capacity)​

Solution 3: Stagger Sync Jobs​

Solution 4: Use Incremental Sync Mode​

Error: "All tokens are in cooldown"​

Solution 1: Wait for Token Recovery​

Solution 2: Add More Tokens​

Solution 3: Reduce Concurrency​

Network Errors​

Error: "Network error: Could not connect to Vimeo API"​

Solution 1: Check Internet Connectivity​

Solution 2: Check Vimeo Status​

Solution 3: Check Firewall Rules​

Solution 4: Increase Timeout​

Error: "SSL certificate verification failed"​

Solution 1: Update CA Certificates​

Solution 2: Check System Time​

Solution 3: Disable SSL Verification (Not Recommended)​

Backend Connectivity Issues​

Dashboard Shows "Backend not reachable"​

Solution 1: Check Backend Is Running​

Solution 2: Verify API Endpoint​

Solution 3: Check Dashboard Configuration​

Solution 4: Check Network/Firewall​

Unknown Errors​

Error: "Unknown error occurred"​

Solution 1: Check Backend Logs​

Solution 2: Check System Resources​

Solution 3: Reproduce with Minimal Example​

Solution 4: Report the Issue​

Partial Failures​

Some Videos in a Sync Job Failed​

Solution 1: Check Backend Logs for Failed Videos​

Solution 2: Retry with Full Sync​

Solution 3: Manually Inspect Failed Videos​

Prevention Strategies​

Best Practices to Avoid Failures​

Diagnostic Checklist​

Getting Help​

Related Guides​

Quick Diagnosis Flowchart

Authentication Errors

Error: "Authentication failed: Invalid API token"

Solution 1: Verify Token Validity

Solution 2: Check Token Scopes

Solution 3: Regenerate Token

Solution 4: Check Account Status

Error: "Forbidden: Access denied to this resource"

Scenario 1: Private Content

Scenario 2: Missing Scopes

Scenario 3: Content Was Deleted

Invalid URL Errors

Error: "Invalid Vimeo URL: Unsupported format"

Solution 1: Check for Typos

Solution 2: Remove Query Parameters

Solution 3: Use Public URL, Not Admin URL

Error: "Invalid Vimeo URL: Resource not found"

Solution 1: Verify URL Exists

Solution 2: Check Privacy Settings

Solution 3: Check for Deleted Content

Rate Limit Errors

Error: "Rate limit exceeded"

Solution 1: Wait and Retry

Solution 2: Enable Token Pool (6x Capacity)

Solution 3: Stagger Sync Jobs

Solution 4: Use Incremental Sync Mode

Error: "All tokens are in cooldown"

Solution 1: Wait for Token Recovery

Solution 2: Add More Tokens

Solution 3: Reduce Concurrency

Network Errors

Error: "Network error: Could not connect to Vimeo API"

Solution 1: Check Internet Connectivity

Solution 2: Check Vimeo Status

Solution 3: Check Firewall Rules

Solution 4: Increase Timeout

Error: "SSL certificate verification failed"

Solution 1: Update CA Certificates

Solution 2: Check System Time

Solution 3: Disable SSL Verification (Not Recommended)

Backend Connectivity Issues

Dashboard Shows "Backend not reachable"

Solution 1: Check Backend Is Running

Solution 2: Verify API Endpoint

Solution 3: Check Dashboard Configuration

Solution 4: Check Network/Firewall

Unknown Errors

Error: "Unknown error occurred"

Solution 1: Check Backend Logs

Solution 2: Check System Resources

Solution 3: Reproduce with Minimal Example

Solution 4: Report the Issue

Partial Failures

Some Videos in a Sync Job Failed

Solution 1: Check Backend Logs for Failed Videos

Solution 2: Retry with Full Sync

Solution 3: Manually Inspect Failed Videos

Prevention Strategies

Best Practices to Avoid Failures

Diagnostic Checklist

Getting Help

Related Guides