Error Reference

Complete reference for all API error codes. Each error includes a machine-readable code, HTTP status, and troubleshooting guidance.

Error Response Format

All errors follow a consistent format with the error wrapped in an error object:

Error Response Structurejson

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong",
    "details": {
      // Additional context (varies by error type)
    },
    "docs_url": "/docs/errors#error-code"
  },
  "request_id": "req_abc123"
}

Tip: Always include the request_id when contacting support for faster issue resolution.

Quick Reference

Code	Status	Description
INVALID_URL	400	Not a valid YouTube URL
BATCH_SIZE_EXCEEDED	400	Too many URLs in batch (max 10)
MAX_VIDEOS_EXCEEDED	400	Too many videos requested (max 25)
API_KEY_ALREADY_EXISTS	400	Active API key exists
NO_API_KEY_TO_REGENERATE	400	No key to regenerate
NO_API_KEY_TO_REVOKE	400	No active key to revoke
USER_ALREADY_EXISTS	400	Account already exists
UNAUTHORIZED	401	Missing or invalid API key
INSUFFICIENT_CREDITS	402	Not enough credits
UPGRADE_REQUIRED	403	Feature requires higher tier
USER_NOT_FOUND	404	User account not found
VIDEO_NOT_FOUND	404	Video not found or private
NO_SUBTITLES	404	Video has no subtitles
LANGUAGE_NOT_AVAILABLE	404	Language not available
INSUFFICIENT_DATA	422	Not enough data for analysis
RATE_LIMITED	429	Rate limit exceeded
INTERNAL_ERROR	500	Unexpected server error
EXTRACTION_FAILED	502	YouTube extraction failed
AUTH_SERVICE_UNAVAILABLE	503	Auth service down
AI_SERVICE_TIMEOUT	504	AI processing timed out

400 Bad Request

The request was malformed or contained invalid parameters.

INVALID_URL400 Bad Request

The provided URL is not a valid YouTube video URL.

Response includes:

•provided_url
•valid_formats

{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "Invalid YouTube URL format. Supported formats: https://www.youtube.com/watch?v=VIDEO_ID, https://youtu.be/VIDEO_ID, https://www.youtube.com/shorts/VIDEO_ID",
    "details": {
      "provided_url": "https://vimeo.com/123456",
      "valid_formats": [
        "https://www.youtube.com/watch?v=VIDEO_ID",
        "https://youtu.be/VIDEO_ID",
        "https://www.youtube.com/shorts/VIDEO_ID"
      ]
    },
    "docs_url": "/docs/errors#invalid-url"
  },
  "request_id": "req_abc123"
}

How to fix:

→Use one of the supported YouTube URL formats
→Ensure the URL contains a valid video ID
→Check for typos in the URL

BATCH_SIZE_EXCEEDED400 Bad Request

The batch request contains too many URLs. Maximum 10 URLs per batch.

Response includes:

•requested
•maximum

{
  "success": false,
  "error": {
    "code": "BATCH_SIZE_EXCEEDED",
    "message": "Batch size exceeded. Maximum 10 URLs allowed per request.",
    "details": {
      "requested": 15,
      "maximum": 10
    },
    "docs_url": "/docs/errors#batch-size-exceeded"
  },
  "request_id": "req_abc123"
}

How to fix:

→Split your URLs into multiple batch requests of 10 or fewer
→Use the playlist endpoint for extracting from playlists (up to 25)

MAX_VIDEOS_EXCEEDED400 Bad Request

The playlist request exceeds the maximum number of videos. Maximum 25 videos per request.

Response includes:

•requested
•maximum

{
  "success": false,
  "error": {
    "code": "MAX_VIDEOS_EXCEEDED",
    "message": "Maximum videos exceeded. You requested 50 but the limit is 25.",
    "details": {
      "requested": 50,
      "maximum": 25
    },
    "docs_url": "/docs/errors#max-videos-exceeded"
  },
  "request_id": "req_abc123"
}

How to fix:

→Reduce the max parameter to 25 or less
→Make multiple requests with different max values if needed

API_KEY_ALREADY_EXISTS400 Bad Request

You already have an active API key. Revoke the existing key before generating a new one.

{
  "success": false,
  "error": {
    "code": "API_KEY_ALREADY_EXISTS",
    "message": "You already have an active API key",
    "docs_url": "/docs/errors#api-key-already-exists"
  },
  "request_id": "req_abc123"
}

How to fix:

→Use your existing API key from the dashboard
→Regenerate your key if you need a new one (invalidates old key)
→Revoke your current key first if you want to start fresh

NO_API_KEY_TO_REGENERATE400 Bad Request

You attempted to regenerate an API key but don't have an active key to regenerate.

{
  "success": false,
  "error": {
    "code": "NO_API_KEY_TO_REGENERATE",
    "message": "No active API key to regenerate. Generate a new key instead.",
    "docs_url": "/docs/errors#no-api-key-to-regenerate"
  },
  "request_id": "req_abc123"
}

How to fix:

→Generate a new API key from your dashboard instead
→You may have previously revoked your key

NO_API_KEY_TO_REVOKE400 Bad Request

You attempted to revoke an API key but don't have an active key to revoke.

{
  "success": false,
  "error": {
    "code": "NO_API_KEY_TO_REVOKE",
    "message": "No active API key to revoke.",
    "docs_url": "/docs/errors#no-api-key-to-revoke"
  },
  "request_id": "req_abc123"
}

How to fix:

→You may have already revoked your key
→Check your dashboard to see your current key status
→Generate a new API key if you need one

USER_ALREADY_EXISTS400 Bad Request

Attempted to create a user account that already exists. This typically occurs during account synchronization.

{
  "success": false,
  "error": {
    "code": "USER_ALREADY_EXISTS",
    "message": "User already exists",
    "docs_url": "/docs/errors#user-already-exists"
  },
  "request_id": "req_abc123"
}

How to fix:

→You already have an account - try signing in instead
→If you believe this is an error, contact support
→Clear your browser cache and try again

401 Unauthorized

Authentication failed. The API key is missing, invalid, or revoked.

UNAUTHORIZED401 Unauthorized

The API key is missing from the request, invalid, or has been revoked.

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "docs_url": "/docs/errors#unauthorized"
  },
  "request_id": "req_abc123"
}

How to fix:

→Ensure the X-API-Key header is included in your request
→Check that your API key is copied correctly (no extra spaces)
→Verify your key hasn't been revoked or regenerated
→Generate a new key from your dashboard if needed

402 Payment Required

Insufficient credits for the requested operation.

INSUFFICIENT_CREDITS402 Payment Required

You don't have enough credits to complete this operation. Credits are used for AI features and comment downloads.

Response includes:

•credits_required
•credits_available

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits for this operation",
    "details": {
      "credits_required": 4,
      "credits_available": 2
    },
    "docs_url": "/docs/errors#insufficient-credits"
  },
  "request_id": "req_abc123"
}

How to fix:

→Check your credit balance in the dashboard
→Credits reset monthly on your billing date
→Upgrade to a higher tier for more monthly credits
→Wait for your credits to reset next billing cycle

403 Forbidden

You don't have permission to access this feature.

UPGRADE_REQUIRED403 Forbidden

This feature requires a Pro or higher subscription tier. Free tier users cannot access AI features, comments, or batch operations.

Response includes:

•feature
•upgrade_url

{
  "success": false,
  "error": {
    "code": "UPGRADE_REQUIRED",
    "message": "AI Summary requires a Pro or higher subscription",
    "details": {
      "feature": "AI Summary",
      "upgrade_url": "/pricing"
    },
    "docs_url": "/docs/errors#upgrade-required"
  },
  "request_id": "req_abc123"
}

How to fix:

→Upgrade to Pro tier at /pricing to access this feature
→AI summaries, comment downloads, and batch operations require Pro+
→Free tier includes subtitle extraction only

404 Not Found

The requested resource was not found.

VIDEO_NOT_FOUND404 Not Found

The video doesn't exist, is private, or has been deleted.

Response includes:

•video_id

{
  "success": false,
  "error": {
    "code": "VIDEO_NOT_FOUND",
    "message": "Video not found or unavailable (ID: abc123). The video may be private, deleted, or the ID may be incorrect.",
    "details": {
      "video_id": "abc123"
    },
    "docs_url": "/docs/errors#video-not-found"
  },
  "request_id": "req_abc123"
}

How to fix:

→Verify the video ID in the URL is correct
→Check if the video is publicly accessible
→Try opening the video in a browser to confirm it exists

NO_SUBTITLES404 Not Found

The video exists but has no subtitles (captions) available.

Response includes:

•video_id

{
  "success": false,
  "error": {
    "code": "NO_SUBTITLES",
    "message": "No subtitles available for this video (ID: dQw4w9WgXcQ). The video may not have any captions enabled.",
    "details": {
      "video_id": "dQw4w9WgXcQ"
    },
    "docs_url": "/docs/errors#no-subtitles"
  },
  "request_id": "req_abc123"
}

How to fix:

→Not all YouTube videos have subtitles
→Try a different video that has captions enabled
→Check if the video has auto-generated captions on YouTube

LANGUAGE_NOT_AVAILABLE404 Not Found

Subtitles exist for this video, but not in the requested language.

Response includes:

•requested_language
•available_languages
•video_id

{
  "success": false,
  "error": {
    "code": "LANGUAGE_NOT_AVAILABLE",
    "message": "Spanish (es) subtitles not available for this video. Available languages: de, en, fr, ja",
    "details": {
      "requested_language": "es",
      "available_languages": ["de", "en", "fr", "ja"],
      "video_id": "dQw4w9WgXcQ"
    },
    "docs_url": "/docs/errors#language-not-available"
  },
  "request_id": "req_abc123"
}

How to fix:

→Check the available_languages array in the error response
→Use one of the available language codes
→Try "en" as it's most commonly available

USER_NOT_FOUND404 Not Found

No user account found. This typically occurs in dashboard/management endpoints.

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User not found",
    "docs_url": "/docs/errors#user-not-found"
  },
  "request_id": "req_abc123"
}

How to fix:

→Ensure you have created an account
→Sign out and sign back in
→Contact support if the issue persists

422 Unprocessable Entity

The request was well-formed but could not be processed due to insufficient data.

INSUFFICIENT_DATA422 Unprocessable Entity

The video doesn't have enough data for the requested operation. For comment analysis, a minimum of 10 comments is required.

Response includes:

•available_count
•required_count
•resource_type

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_DATA",
    "message": "Not enough comments for analysis. Found 5, need at least 10.",
    "details": {
      "available_count": 5,
      "required_count": 10,
      "resource_type": "comments"
    },
    "docs_url": "/docs/errors#insufficient-data"
  },
  "request_id": "req_abc123"
}

How to fix:

→Try a different video with more comments
→Comment analysis requires at least 10 comments
→Check if comments are enabled on the video

429 Too Many Requests

You've exceeded your rate limit for the current period.

RATE_LIMITED429 Too Many Requests

You've exceeded your tier's request limit. Wait for the limit to reset or upgrade your plan.

Response includes:

•retry_after
•limit
•window

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. You can make 100 requests per 1 day. Please try again in 3600 seconds.",
    "details": {
      "retry_after": 3600,
      "limit": 100,
      "window": "1 day"
    },
    "docs_url": "/docs/errors#rate-limited"
  },
  "request_id": "req_abc123"
}

How to fix:

→Wait for the time specified in retry_after
→Implement exponential backoff in your application
→Consider caching responses on your end
→Upgrade to a higher tier for more requests

500 Internal Server Error

An unexpected error occurred on our servers.

INTERNAL_ERROR500 Internal Server Error

Something went wrong on our end. Please try again or contact support.

Response includes:

•request_id

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later. If the problem persists, contact support with the request ID.",
    "details": {
      "request_id": "req_abc123"
    },
    "docs_url": "/docs/errors#internal-error"
  },
  "request_id": "req_abc123"
}

How to fix:

→Wait a moment and retry your request
→Check our status page for any ongoing incidents
→Contact support with your request_id if the error persists

502 Bad Gateway

Failed to communicate with an upstream service (YouTube).

EXTRACTION_FAILED502 Bad Gateway

Failed to extract subtitles from YouTube. This is usually temporary.

Response includes:

•reason
•video_id

{
  "success": false,
  "error": {
    "code": "EXTRACTION_FAILED",
    "message": "Failed to extract subtitles from YouTube. This may be due to YouTube rate limiting or temporary unavailability.",
    "details": {
      "video_id": "dQw4w9WgXcQ",
      "reason": "YouTube returned an error"
    },
    "docs_url": "/docs/errors#extraction-failed"
  },
  "request_id": "req_abc123"
}

How to fix:

→Wait a few minutes and retry
→Try a different video to confirm the API is working
→This often resolves on its own within minutes
→Contact support if it persists for the same video

503 Service Unavailable

A dependent service is temporarily unavailable.

AUTH_SERVICE_UNAVAILABLE503 Service Unavailable

The authentication service is temporarily unavailable.

{
  "success": false,
  "error": {
    "code": "AUTH_SERVICE_UNAVAILABLE",
    "message": "Authentication service temporarily unavailable. Please try again in a few moments.",
    "docs_url": "/docs/errors#auth-service-unavailable"
  },
  "request_id": "req_abc123"
}

How to fix:

→Wait a few seconds and retry
→This is usually resolved quickly
→Check our status page for any ongoing incidents

504 Gateway Timeout

An upstream service took too long to respond.

AI_SERVICE_TIMEOUT504 Gateway Timeout

The AI service (OpenAI) took too long to respond. This may occur for very long videos or during high API usage.

Response includes:

•timeout_seconds

{
  "success": false,
  "error": {
    "code": "AI_SERVICE_TIMEOUT",
    "message": "AI service timed out after 30 seconds. Please try again.",
    "details": {
      "timeout_seconds": 30
    },
    "docs_url": "/docs/errors#ai-service-timeout"
  },
  "request_id": "req_abc123"
}

How to fix:

→Wait a moment and retry your request
→Try a shorter video (long videos take more processing time)
→If the issue persists, the AI service may be experiencing high load
→Contact support if timeouts continue