Error Reference

Error Response Format

All errors follow a consistent structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      // Optional additional context
    }
  }
}

HTTP Status Codes

Status Code	Meaning	When It Occurs
`200`	Success	Request completed successfully
`202`	Accepted	Async job created, use job ID to poll status
`400`	Bad Request	Invalid input or parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	API key lacks required permissions
`404`	Not Found	Resource doesn’t exist
`408`	Request Timeout	Operation took too long
`429`	Too Many Requests	Rate limit or quota exceeded
`500`	Internal Server Error	Server-side error occurred

Error Codes Reference

Authentication Errors (401)

Error Code	Message	Solution
`UNAUTHORIZED`	Request lacks authentication	Include X-API-Key header
`INVALID_API_KEY`	Invalid or inactive API key	Check your API key is correct and active
`API_KEY_INACTIVE`	API key has been deactivated	Create a new API key

Example:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or inactive API key"
  }
}

Authorization Errors (403)

Error Code	Message	Solution
`FORBIDDEN`	Insufficient permissions	Upgrade your plan or contact support

Validation Errors (400)

Error Code	Message	Solution
`INVALID_INPUT`	Validation failed	Check request parameters match schema
`INVALID_VIDEO_ID`	Invalid YouTube video ID or URL	Verify the video ID is correct
`MISSING_PARAMETER`	Required parameter is missing	Include all required parameters
`INVALID_URL`	Invalid URL provided	Ensure URL is well-formed
`CRAWL_LIMIT_EXCEEDED`	Crawl limit too high	Reduce limit to max 1000 pages

Example:

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed",
    "details": {
      "issues": [
        {
          "path": "format",
          "message": "Invalid format. Expected: json, text, srt, or vtt"
        }
      ]
    }
  }
}

Resource Errors (404)

Error Code	Message	Solution
`NOT_FOUND`	Resource not found	Verify the resource ID exists
`KEY_NOT_FOUND`	API key not found	Check the API key is valid
`CHANNEL_NOT_FOUND`	YouTube channel not found	Verify the channel ID
`PLAYLIST_NOT_FOUND`	YouTube playlist not found	Verify the playlist ID
`TRANSCRIPT_UNAVAILABLE`	Video transcript not available	Try a different video or check if captions exist
`JOB_NOT_FOUND`	Job ID not found	Verify the job ID is correct
`WEBHOOK_NOT_FOUND`	Webhook not found	Check the webhook ID

Rate Limiting Errors (429)

Error Code	Message	Solution
`RATE_LIMIT_EXCEEDED`	Too many requests	Wait for rate limit to reset (check X-RateLimit-Reset header)
`QUOTA_EXCEEDED`	Monthly quota exhausted	Wait for quota reset or enable auto-recharge

Example:

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota exhausted. Enable auto-recharge or upgrade your plan.",
    "details": {
      "limit": 1000,
      "remaining": 0
    }
  }
}

YouTube Specific Errors

Error Code	Status	Message	Solution
`TRANSCRIPT_UNAVAILABLE`	404	Video transcript not available	Video may not have captions
`LANGUAGE_NOT_SUPPORTED`	400	Language not supported	Try ‘en’ or check available languages
`CHANNEL_NOT_FOUND`	404	YouTube channel not found	Verify channel ID is correct
`PLAYLIST_NOT_FOUND`	404	YouTube playlist not found	Verify playlist ID is correct

Scraping Errors

Error Code	Status	Message	Solution
`SCRAPING_FAILED`	500	Failed to scrape URL	URL may be inaccessible or blocked
`INVALID_URL`	400	Invalid URL provided	Check URL format
`CRAWL_TIMEOUT`	408	Crawl operation timed out	Reduce crawl limit or retry
`CRAWL_LIMIT_EXCEEDED`	400	Crawl limit too high	Maximum 1000 pages per crawl

Job Errors

Error Code	Status	Message	Solution
`JOB_NOT_FOUND`	404	Job ID not found	Verify job ID is correct
`JOB_FAILED`	500	Job processing failed	Check job details for specific error
`JOB_TIMEOUT`	408	Job timed out	Retry with smaller batch

Server Errors (500)

Error Code	Message	Solution
`INTERNAL_ERROR`	Internal server error	Retry request, contact support if persists
`DATABASE_ERROR`	Database operation failed	Retry request
`EXTERNAL_SERVICE_ERROR`	External service unavailable	Retry request, check status page

Handling Errors in Your Code

TypeScript/JavaScript

try {
  const response = await fetch('https://api.scriptbase.app/api/v1/videos/invalid_id', {
    headers: { 'X-API-Key': 'sk_your_key' }
  });

  const data = await response.json();

  if (!data.success) {
    switch (data.error.code) {
      case 'INVALID_VIDEO_ID':
        console.error('Invalid video ID provided');
        break;
      case 'QUOTA_EXCEEDED':
        console.error('Quota exceeded. Waiting for reset...');
        break;
      case 'RATE_LIMIT_EXCEEDED':
        const retryAfter = response.headers.get('Retry-After');
        console.error(`Rate limited. Retry after ${retryAfter} seconds`);
        break;
      default:
        console.error(`Error: ${data.error.message}`);
    }
  }
} catch (error) {
  console.error('Network error:', error);
}

Python

import requests
import time

def fetch_video(video_id, api_key):
    response = requests.get(
        f'https://api.scriptbase.app/api/v1/videos/{video_id}',
        headers={'X-API-Key': api_key}
    )
    
    data = response.json()
    
    if not data.get('success'):
        error = data['error']
        
        if error['code'] == 'RATE_LIMIT_EXCEEDED':
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f'Rate limited. Waiting {retry_after} seconds...')
            time.sleep(retry_after)
            return fetch_video(video_id, api_key)  # Retry
        
        elif error['code'] == 'QUOTA_EXCEEDED':
            raise Exception('Monthly quota exceeded')
        
        else:
            raise Exception(f"API Error: {error['message']}")
    
    return data['data']

Go

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

type ErrorResponse struct {
    Success bool `json:"success"`
    Error   struct {
        Code    string                 `json:"code"`
        Message string                 `json:"message"`
        Details map[string]interface{} `json:"details,omitempty"`
    } `json:"error"`
}

func fetchVideo(videoID, apiKey string) error {
    req, _ := http.NewRequest(
        "GET",
        fmt.Sprintf("https://api.scriptbase.app/api/v1/videos/%s", videoID),
        nil,
    )
    req.Header.Set("X-API-Key", apiKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    var errorResp ErrorResponse
    if err := json.Unmarshal(body, &errorResp); err == nil && !errorResp.Success {
        switch errorResp.Error.Code {
        case "RATE_LIMIT_EXCEEDED":
            retryAfter := resp.Header.Get("Retry-After")
            fmt.Printf("Rate limited. Retry after %s seconds\n", retryAfter)
            return fmt.Errorf("rate limit exceeded")
        case "QUOTA_EXCEEDED":
            return fmt.Errorf("quota exceeded")
        default:
            return fmt.Errorf("API error: %s", errorResp.Error.Message)
        }
    }

    return nil
}

Response Headers for Debugging

When handling errors, check these headers for additional context:

Header	Description	Example
`X-RateLimit-Remaining`	Requests remaining this period	`45`
`X-RateLimit-Reset`	Unix timestamp when limit resets	`1704326400`
`Retry-After`	Seconds to wait before retrying	`60`
`X-Credits-Remaining`	Credits remaining in quota	`850`

Common Error Scenarios

Quota Exceeded Mid-Month

Problem: You’ve exhausted your monthly quota before the reset date.Solutions:

Enable auto-recharge in dashboard
Upgrade to a higher tier
Wait for monthly reset
Optimize your requests to use fewer credits

Rate Limit Exceeded

Problem: Too many requests in a short time period.Solutions:

Implement exponential backoff
Respect the Retry-After header
Batch your requests when possible
Upgrade to a higher tier with higher rate limits

Transcript Not Available

Problem: Video doesn’t have transcripts/captions.Solutions:

Check if the video has captions on YouTube
Try different language codes
Handle this gracefully in your application

Invalid Video ID

Problem: The video ID format is incorrect or video doesn’t exist.Solutions:

Verify the video ID is 11 characters
Ensure the video exists on YouTube
Check for typos in the ID

Need Help?

If you’re experiencing errors that aren’t covered here:

Check the status page for ongoing incidents
Review your implementation against the API Reference
Contact support with the error code and request ID

Getting Started

Core Concepts

Guides

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors (401)

Authorization Errors (403)

Validation Errors (400)

Resource Errors (404)

Rate Limiting Errors (429)

YouTube Specific Errors

Scraping Errors

Job Errors

Server Errors (500)

Handling Errors in Your Code

TypeScript/JavaScript

Python

Go

Response Headers for Debugging

Common Error Scenarios

Need Help?

Getting Started

Core Concepts

Guides

​Error Response Format

​HTTP Status Codes

​Error Codes Reference

​Authentication Errors (401)

​Authorization Errors (403)

​Validation Errors (400)

​Resource Errors (404)

​Rate Limiting Errors (429)

​YouTube Specific Errors

​Scraping Errors

​Job Errors

​Server Errors (500)

​Handling Errors in Your Code

​TypeScript/JavaScript

​Python

​Go

​Response Headers for Debugging

​Common Error Scenarios

​Need Help?

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors (401)

Authorization Errors (403)

Validation Errors (400)

Resource Errors (404)

Rate Limiting Errors (429)

YouTube Specific Errors

Scraping Errors

Job Errors

Server Errors (500)

Handling Errors in Your Code

TypeScript/JavaScript

Python

Go

Response Headers for Debugging

Common Error Scenarios

Need Help?