Developer Guides

Error Handling

HTTP Status Codes

When calling the Sync API, you may encounter the following HTTP status codes. These are returned at the HTTP level before any generation-specific error codes.

Status CodeNameCommon CauseResolution
401UnauthorizedInvalid or missing API key. The SYNC_API_KEY environment variable is not set or the key has been revoked.Create a new key from the Dashboard. Verify the key is included in the x-api-key header.
402Payment RequiredInsufficient credits or plan limits exceeded. Commonly seen during lip sync tests when the account has no active subscription or has exhausted free-tier generations.Check your plan limits on the Billing page. Free tier allows 3 generations/month, max 20s each. Upgrade your plan or wait for the next billing cycle.
413Payload Too LargeFile upload exceeds the 20 MB limit.Use a public URL instead of direct upload for larger files. Compress or trim the media before uploading.
429Too Many RequestsRate limit exceeded. The API allows 60 requests/minute on POST /v2/generate.Implement exponential backoff. See the Rate Limits page for details.
500Internal Server ErrorServer-side error during processing.Retry after a brief delay. If persistent, check status.sync.so for service status.
503Service UnavailableService temporarily down for maintenance or due to high load.Retry with exponential backoff. Check status.sync.so for ongoing incidents.

What do Sync API error codes mean?

Here’s a comprehensive list of Sync lip sync API error codes you may encounter, grouped by category and ordered from most common to least common.

Input Validation Errors

generation_unsupported_model

Message: “The requested model is not supported for this operation.”

Description: This error is thrown when you attempt to use a model that is not compatible with the current operation or API endpoint.

Resolution:

  1. Check the documentation to see which models are supported for this specific API call.
  2. Update your request to use a supported model.
  3. If you believe this is an error, please contact our support team with details of your use case.

generation_media_metadata_missing

Message: “Required media metadata is missing from the request.”

Description: This error occurs when the media file lacks essential metadata for processing. The required metadata fields include:

  • duration: The length of the media in seconds (for both audio and video)
  • frame_rate: The number of frames per second (for video content only)

Resolution:

  1. Ensure that your media file includes the required metadata embedded within it:
    • For audio files: Verify that the duration metadata is present.
    • For video files: Check that both duration and frame_rate metadata are included.
  2. Use media editing tools to add or update the necessary metadata to your file.
  3. Verify that the metadata is correctly embedded and readable before submitting the media for processing.
  4. For persistent issues, contact our support team for guidance on proper media preparation and metadata requirements.

generation_audio_length_exceeded

Message: “The provided audio exceeds the maximum allowed length.”

Description: This error is thrown when the audio file submitted for processing is longer than the maximum permitted duration of 300 seconds (5 minutes).

Resolution:

  1. Trim or split your audio file to meet the length requirements.
  2. If you need to process longer audio files, consider batching your requests into smaller chunks or contact support for alternative solutions.

generation_text_length_exceeded

Message: “Text must be less than 5000 characters in one generation.”

Description: This error occurs when the text provided for text-to-speech (TTS) generation exceeds the maximum allowed length of 5,000 characters.

Resolution:

  1. Reduce the length of your text input to 5,000 characters or fewer.
  2. Consider breaking longer text into multiple smaller requests.
  3. Remove unnecessary content or use more concise language to fit within the limit.

generation_audio_missing

Message: “No audio file was provided in the request.”

Description: This error occurs when an audio file is expected but not included in the API request.

Resolution:

  1. Ensure that you’re including the audio file in your request payload.
  2. Verify that the audio file is properly encoded and formatted as per the API requirements.
  3. For persistent issues, contact our support team for guidance on proper audio file preparation and submission.

generation_video_missing

Message: “No video file was provided in the request.”

Description: This error occurs when a video file is expected but not included in the API request.

Resolution:

  1. Make sure you’re including the video file in your request payload.
  2. Verify that the video file is properly encoded and formatted according to the API specifications.
  3. For persistent issues, contact our support team for guidance on proper video file preparation and submission.

generation_input_validation_failed

Message: “Failed to validate input: [specific error details or ‘unknown validation failure’]”

Description: This error occurs when the provided input data does not meet the required validation criteria for processing. The error message includes specific details about what validation failed, which can help identify issues with file formats, metadata, or other input parameters that don’t conform to expected specifications. If specific details aren’t available, the message will indicate “unknown validation failure.”

Resolution:

  1. Review your input data to ensure it meets all API requirements and specifications.
  2. Check that all required fields are present and properly formatted.
  3. Verify that file formats, sizes, and other parameters are within acceptable limits.
  4. If the issue persists, contact our support team with details about your input data for further assistance.

Batch API Errors

batch_concurrency_limit_reached

Message: “Batch concurrency limit reached. You have X active batches and your plan allows Y. Please wait for existing batches to complete or upgrade your plan for higher limits.”

Description: This error occurs when you attempt to create a new batch while already at your plan’s batch concurrency limit.

Resolution:

  1. Wait for one or more of your active batches to complete before submitting new ones.
  2. Check your active batches using the List Batches endpoint to monitor their progress.
  3. Consider upgrading to a higher plan if you need more concurrent batch processing capacity.

batch_plan_required

Message: “This endpoint is only available for scale and enterprise plans. Please upgrade your plan.”

Description: The Batch API is only available for Scale plan subscribers and above.

Resolution:

  1. Upgrade your subscription to Scale plan or higher to access batch processing features.
  2. Contact our sales team to discuss plan options that meet your batch processing needs.

batch_file_too_large

Message: “File size exceeds the maximum limit of 5MB.”

Description: The uploaded batch file exceeds the 5MB size limit.

Resolution:

  1. Reduce the size of your batch file by splitting it into smaller batches.
  2. Remove unnecessary data or optimize your JSON formatting to reduce file size.
  3. Consider processing your data in multiple smaller batches instead of one large batch.

batch_too_many_requests

Message: “Number of records exceeds the maximum limit of 1,000.”

Description: Your batch file contains more than the maximum allowed 1,000 generation requests.

Resolution:

  1. Split your batch into multiple smaller batches, each containing 1,000 or fewer requests.
  2. Process your data in chunks to stay within the limit.

batch_insufficient_records

Message: “Input file must contain at least 20 records. Found X record(s).”

Description: Your batch file contains fewer than the minimum required 20 generation requests.

Resolution:

  1. Add more generation requests to your batch file to meet the minimum requirement of 20 records.
  2. Consider combining multiple smaller batches into a single batch that meets the minimum threshold.
  3. If you have fewer than 20 requests to process, use the individual Generate API instead of batch processing.

batch_invalid_jsonl

Message: “Invalid JSON at line X: [specific error message]”

Description: The batch file contains invalid JSON formatting on a specific line.

Resolution:

  1. Validate your JSON Lines (.jsonl) file format - each line must be valid JSON.
  2. Check the specific line mentioned in the error message for syntax errors.
  3. Ensure there are no trailing commas, missing quotes, or other JSON formatting issues.
  4. Use a JSON validator to check each line of your file.

batch_duplicate_request_id

Message: “Duplicate request_id found at line X: [request_id]”

Description: The batch file contains duplicate request_id values, which must be unique within each batch.

Resolution:

  1. Ensure all request_id values in your batch file are unique.
  2. Review your batch generation logic to prevent duplicate IDs.
  3. Consider using UUIDs or timestamps to ensure uniqueness.

batch_invalid_endpoint

Message: “Invalid endpoint specified. Only ‘/v2/generate’ is supported.”

Description: The batch file contains requests for unsupported endpoints.

Resolution:

  1. Ensure all requests in your batch file use "endpoint": "/v2/generate".
  2. Currently, only the generate endpoint is supported for batch processing.

System and Processing Errors

generation_timeout

Message: “The generation process exceeded the maximum allowed time.”

Description: This is an internal error that occurs when our system is under high load, causing the requested operation to take longer than the allotted time to complete.

Resolution:

  1. Retry your request after a short delay, as the high load may be temporary.
  2. If possible, try submitting your request during off-peak hours.
  3. Consider breaking down large requests into smaller, more manageable chunks.
  4. If the issue persists, contact our support team to report the problem and discuss potential solutions.

generation_pipeline_failed

Message: “An error occurred in the generation pipeline.”

Description: This error indicates a failure in one of the internal processing steps of the generation pipeline.

Resolution:

  1. Review your input data to ensure it meets all the required specifications.
  2. Try resubmitting the request, as some pipeline errors may be temporary.
  3. If the problem continues, reach out to our support team with details about your request and the specific error message for further investigation.

generation_database_error

Message: “An error occurred while accessing the database.”

Description: This error indicates a problem with database operations during the generation process.

Resolution:

  1. Verify that your request doesn’t contain any invalid or conflicting data that might cause database issues.
  2. Try your request again after a short wait, as database errors can sometimes be temporary.
  3. If the problem continues, report the issue to our support team, providing details about your request and any specific error messages you received.

generation_internal_auth

Message: “Authentication failed for internal generation service.”

Description: This error occurs when there’s an issue with our internal authentication process. If you get this error, contact our support team so we can get it fixed.

generation_unhandled_error

Message: “An unexpected error occurred during the generation process.”

Description: This is a catch-all error for unforeseen issues that aren’t covered by more specific error codes.

Resolution:

  1. Check all aspects of your request for any potential issues or inconsistencies.
  2. Try the request again, as some unhandled errors may be due to temporary system glitches.
  3. If the error persists, contact our support team with a detailed description of your request and the steps to reproduce the error.

generation_infra_storage_error

Message: “An error occurred while accessing the storage on infra layer.”

Description: This error indicates a problem with accessing or managing storage resources during the generation process. This can occur due to temporary storage service issues or connectivity problems.

Resolution:

  1. Retry your request after a short delay, as storage errors are often temporary.
  2. Ensure your input files are accessible and not corrupted.
  3. If the problem persists, contact our support team as this may indicate a broader infrastructure issue.

generation_infra_resource_exhausted

Message: “The infra resources are exhausted.”

Description: This error occurs when the infrastructure resources required for processing your request are temporarily unavailable or at capacity.

Resolution:

  1. Wait a few minutes and retry your request, as resource availability fluctuates.
  2. Consider submitting your request during off-peak hours when resources are more readily available.
  3. If you frequently encounter this error, contact our support team to discuss your usage patterns and potential solutions.

generation_infra_service_unavailable

Message: “The infra service is unavailable.”

Description: This error indicates that one or more infrastructure services required for processing are temporarily unavailable. This can be due to maintenance, connectivity issues, or service outages.

Resolution:

  1. Check our status page for any ongoing service issues or maintenance windows.
  2. Retry your request after a short delay, as service availability issues are typically temporary.
  3. If the service remains unavailable for an extended period, contact our support team for updates and assistance.

General Troubleshooting Tips

  1. Check your API key: Ensure you’re using the correct API key and that it is not revoked.
  2. Verify request format: Double-check that your API request is properly formatted and includes all required parameters.
  3. Review rate limits: Make sure you haven’t exceeded your API rate limits.
  4. Check service status: Visit our status page to see if there are any ongoing service issues.
  5. Consult the documentation: Our API documentation may have been updated with new information or changes.

Finding Generation IDs from Studio

If you need to find a generation ID for troubleshooting purposes, you can easily locate it through the Studio interface. Both Studio Pro and Studio Lite modes follow the same basic process:

For Studio Pro Mode: First click on the “History” button in the Studio interface, then follow the steps below.

For Studio Lite Mode: Go directly to the steps below.

  1. Locate Your Generation: Find the generation thumbnail you need the ID for
  2. Access the Menu: Hover over the generation thumbnail and click the three dots menu that appears
  3. Copy the Job ID: Select “copy job id” from the dropdown menu
Screenshot showing how to copy job ID from Studio three dots menu

For Agent Mode: In Agent Mode, you can find generation IDs in two ways:

  1. Sessions Sidebar: Click the dropdown menu (three dots) next to any session entry in the sidebar and select “Copy Job ID”
  2. Error Card: When a generation fails, click the “Copy Job ID” button directly on the error notification card

This generation ID can then be used when contacting support or when making API calls to retrieve specific generation details.

If you’re still experiencing issues after trying these steps, check the Troubleshooting page for common problems and solutions, or reach out to our support team for assistance.

  • Rate Limits — understand API rate limiting and how to handle throttled requests
  • Webhooks — receive real-time notifications when generation jobs complete or fail
  • Quickstart — get up and running with your first Sync API call

Support Knowledge Base

Frequently Asked Questions

A 400 error means your request has invalid input. Common causes include a malformed URL, unsupported media format, missing required fields, or audio exceeding the 300-second limit. Check the specific error code in the response body for details on what to fix.

A generation in PENDING status is waiting for processing resources. During periods of high demand, jobs may queue briefly before starting. If a generation stays in PENDING for an extended time, retry the request or contact support for assistance.

Submit a new generation request with the same input parameters. There is no built-in retry endpoint. For production systems, implement retry logic with exponential backoff for transient errors like 429 rate limits or 500 server errors. Check the error code before retrying.