Skip to main content

Troubleshooting

Quick Diagnostics​

# Is the service running?
curl http://video-scraper-api:80/docs

# Test the hybrid endpoint
curl "http://video-scraper-api:80/api/hybrid/video_data?url=https://www.tiktok.com/@tiktok/video/7218694761253735723"

Common Errors​

code is not 200​

The API always returns HTTP 200 but puts the real status in the code field. Check data for the error message.

{
  "code": 400,
  "router": "/api/douyin/web/fetch_one_video",
  "data": { "message": "..." }
}

Douyin endpoints return auth errors​

Cause: Douyin cookie is missing, expired, or malformed.

Fix:

  1. Get a fresh Douyin cookie from your browser (see Cookie Management)
  2. Push it to the API:
curl -X POST http://video-scraper-api:80/api/hybrid/update_cookie \
  -H "Content-Type: application/json" \
  -d '{"service": "douyin", "cookie": "FRESH_COOKIE"}'
  1. Retry the endpoint

Video CDN URL returns 403​

Cause: You're trying to download the CDN URL directly without proper browser headers.

Fix: Use the download proxy endpoint instead:

GET /api/download?url=<original_share_url>&with_watermark=false

Set the n8n HTTP Request node response format to File / Binary.

422 Validation Error​

Cause: Missing or wrong query parameter name.

Fix: Check the parameter names — they're case-sensitive. Common mistakes:

  • itemId (TikTok) vs aweme_id (Douyin/TikTok App) — these are different and non-interchangeable
  • secUid (TikTok web) vs sec_user_id (Douyin) — different parameter names for the same concept

Check the API Reference for exact parameter names per endpoint.

Connection refused on localhost:8092​

Cause: Port 8092 is only accessible on the host machine. Agent containers can't reach localhost on the host.

Fix: Use the Docker network hostname instead:

http://video-scraper-api:80  ✅
http://localhost:8092         ❌ (from inside containers)

Video data returns but download URLs are empty​

Cause: The video may be private, deleted, or geo-restricted.

Fix: Check the video_data object — if URLs are empty strings, the content is likely unavailable in your region or has been taken down. Nothing to fix on the API side.

Bilibili video has no audio when downloaded​

Cause: Bilibili separates video and audio streams at higher qualities.

Fix: Use the /api/download proxy — it automatically merges the video and audio streams for Bilibili. Direct playURL fetching will give you separate streams.

scraper.shin0x.space not resolving​

Cause: DNS or Caddy issue.

Fix:

  1. Confirm the container is running (Dan's territory)
  2. Check Caddy logs for the reverse proxy
  3. If the external URL is down, use the internal URL from n8n: http://video-scraper-api:80

Still Stuck?​

  1. Check the container logs (DevOps Dan): docker logs video-scraper-api
  2. Check the cookie refresh log: cat /opt/nops-labs/Video-Scraper-API/logs/cookie-refresh.log
  3. Hit the live Swagger UI to test the endpoint interactively: https://scraper.shin0x.space/docs
  4. Ping <@U0AFHDRK1H9> (Backend Boris) in #core-tech-engineer