Rate Limiting & Error Handling Guide

This guide provides comprehensive documentation on rate limiting policies and error handling for the Transcript Downloader API. Understanding these policies will help you build a robust and reliable integration.

Rate Limiting Overview

Our API implements rate limiting to ensure fair usage and maintain service stability for all users. Rate limits are applied at multiple levels to protect both individual endpoints and the overall system.

Global API Rate Limit

📋 Note: Rate limits are applied per authenticated user. If you exceed the limit, you’ll receive a 429 Too Many Requests response.

Endpoint-Specific Rate Limits

Download Endpoints

Authentication Endpoints

YouTube API Quotas

YouTube API access is subject to daily quota limits to comply with YouTube’s terms of service.

Quota Consumption

Quota Limits

⚠️ Important: When your daily quota is exhausted, you’ll receive a 429 error. Quota resets automatically at midnight UTC.

Instagram API Considerations

Instagram content fetching operates asynchronously due to the nature of data retrieval.

Processing Behavior

📋 Technical Details:

• Profile/Content jobs: 120 attempts × 30s = 60 minutes maximum
• List jobs: 60 attempts × 180s = 3 hours maximum
• These intervals are optimized for Instagram’s data retrieval patterns

Polling Recommendations

Error Codes Reference

HTTP Status Codes

Common Error Messages

Authentication Errors

Balance Errors

Rate Limit Errors

Content Errors

Processing Errors

Retry Strategies

Exponential Backoff

For retryable errors (429, 500, 503), implement exponential backoff with the following recommended values:

• Base delay: 1 second
• Max delay: 60 seconds
• Max attempts: 5

With each failed attempt, double the wait time until reaching the maximum delay.

Polling Best Practices

For asynchronous operations (Instagram content, audio processing), use the recommended polling intervals below. Continue polling while the status is pending, and stop when you receive success or failed.

Polling Intervals by Operation

Response Headers

Rate Limit Headers

When approaching or exceeding rate limits, the API returns helpful headers:

Best Practices Summary

Do’s ✅

• Implement exponential backoff for failed requests
• Cache successful responses to reduce API calls
• Use polling for async operations instead of repeated submissions
• Monitor your quota usage in the dashboard
• Handle all error codes gracefully in your application

Don’ts ❌

• Don’t retry immediately after receiving a 429 error
• Don’t submit duplicate requests for the same content
• Don’t poll more frequently than recommended intervals
• Don’t ignore error responses - they contain useful debugging info
• Don’t hardcode retry limits - make them configurable

Error Response Format

All error responses follow a consistent JSON format with an error field containing the error message and a status field set to "error".

Validation errors include a message field with a general description and an errors object containing field-specific validation messages.

Support

If you’re experiencing persistent errors or need assistance with rate limiting issues:

• Review your API usage in the Dashboard
• Check our API Documentation for endpoint details
• Contact support at https://transcriptdownloader.com/contact-transcript-downloader