Error Handling

Learn how to handle errors from the CleanScript API in your applications.

Error Response Format

When an error occurs, the API returns a JSON object with a detail field containing the error message.

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request.

StatusDescriptionCommon Causes
200SuccessThe request was successful.
400Bad RequestInvalid parameters or unsupported YouTube URL.
401UnauthorizedMissing or invalid API key in the Authorization header.
403ForbiddenQuota exceeded for your account. Upgrade your plan or wait until the quota resets.
429Too Many RequestsRate limit exceeded. Slow down your request rate.
500Internal Server ErrorAn unexpected error occurred on the server. Contact support if the issue persists.

Common Error Scenarios

Authentication Errors

{
  "detail": "Unauthorized"
}

This error occurs when your API key is missing, invalid, or has been revoked. Ensure you're including a valid API key in the Authorization header.

Quota Errors

{
  "detail": "Quota exceeded. Limit of 3600 seconds until 2025-03-10T00:00:00Z."
}

This error occurs when you've used up your quota for the current billing cycle. The error message includes your limit and when the quota will reset.

Rate Limit Errors

{
  "detail": "Rate limit exceeded. Limit of 60 requests per minute."
}

This error occurs when you've made too many requests in a short period. Implement exponential backoff or reduce your request rate.

Validation Errors

{
  "detail": "Invalid YouTube URL provided."
}

This error occurs when the provided YouTube URL is invalid or not supported. Ensure you're using a valid YouTube URL.

Error Handling Best Practices

  • Always check the HTTP status code and handle errors appropriately
  • Implement exponential backoff for rate limit (429) errors
  • Log detailed error information for debugging
  • Display user-friendly error messages in your application
  • Set up monitoring to alert you of persistent API errors

Error Handling Examples

Error Handling Examples

1// Example of error handling in JavaScript
2async function getTranscript(videoId, apiKey) {
3  try {
4    const response = await fetch(
5      `https://api.cleanscript.ai/v1/transcript?videoId=${videoId}`,
6      {
7        method: 'GET',
8        headers: {
9          'Authorization': `Bearer ${apiKey}`,
10          'Accept': 'application/json',
11        },
12      }
13    );
14    
15    // Check for HTTP error status
16    if (!response.ok) {
17      const errorData = await response.json();
18      
19      // Handle specific error types
20      switch (response.status) {
21        case 401:
22          throw new Error(`Authentication error: ${errorData.detail}`);
23        case 403:
24          throw new Error(`Quota exceeded: ${errorData.detail}`);
25        case 429:
26          throw new Error(`Rate limit exceeded: ${errorData.detail}`);
27        default:
28          throw new Error(`API error (${response.status}): ${errorData.detail}`);
29      }
30    }
31    
32    const data = await response.json();
33    return data;
34  } catch (error) {
35    // Log the error and rethrow
36    console.error('Error fetching transcript:', error);
37    throw error;
38  }
39}