Zur Navigation springen
Entwickleranleitungen

Error Handling

Retrying generation creation

For POST /v2/generate, send an Idempotency-Key on the first attempt and reuse it with the same payload on every retry. The guide covers replay responses, payload conflicts, retention, and all IDEMPOTENCY_* errors. A lost response or IDEMPOTENCY_OUTCOME_UNKNOWN does not authorize a fresh key or an unkeyed retry. An unknown response may include generationId; poll it when available.

Without a key, a create timeout or transport failure can leave acceptance uncertain. Confirm the outcome before submitting again. General backoff advice below does not make an unkeyed create safe to repeat.

HTTP Status Codes

When calling the Sync Labs 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 RequiredThe account cannot start another generation because of billing or plan state. Common causes include exhausted free-tier generations, no active paid plan for paid-only usage, an unpaid usage invoice, or a plan limit being exceeded.Check your plan and invoices on the Billing page. Free accounts allow 3 shared video generations/month, max 15s each, including up to all 3 on sync-3. Upgrade your plan, resolve any unpaid invoice, or wait for the next billing cycle.
413Payload Too LargeA file uploaded directly to POST /v2/generate exceeds the 5 GiB per-file limit. The body carries errorCode: generation_input_validation_failed. No generation is created and no credits are held.Use a smaller file, or pass the file by public URL. Files within 5 GiB must also fit your plan’s file size limit.
429Too Many RequestsRate limit exceeded — see Rate Limits page for per-endpoint limits.Implement exponential backoff. See the Rate Limits page for details.
500Internal Server ErrorServer-side error during processing.Retry after a brief delay. The body carries errorCode: internal_error and a requestId — include the requestId when contacting support so we can locate the failing request directly. If persistent, check status.sync.so for service status.
503Service UnavailableService temporarily down for maintenance, high load, or a provider dependency outage.Retry with exponential backoff, honoring the Retry-After header when present. Check status.sync.so for ongoing incidents.
504Gateway TimeoutA sync. labs service or provider dependency timed out before it could complete the request.Retry with exponential backoff. If the body includes a requestId and the timeout keeps happening, include it when contacting support.

HTML 403 or Cloudflare Access denied

If a request to api.sync.so returns an HTML page identifying Cloudflare with HTTP 403, Access denied, or error 1010, treat it separately from the JSON API errors below. A Cloudflare block can occur before API validation, so it does not by itself establish that your API key, plan, or media is invalid.

Stop repeated retries and contact support@sync.so with the request method and endpoint, UTC timestamp, Cloudflare Ray ID, client/SDK version, and a redacted response or screenshot. For uploads, include the content type and file sizes. Do not send API keys, authorization headers, or signed media URLs. Support needs the specific response to investigate; do not assume that every 403 has the same cause.

A 403 from a presigned storage upload URL is a different case: check the Asset Uploads troubleshooting guide for content-type and URL-expiry checks.

Machine-Readable Error Codes

Every failed generation carries a stable, machine-readable errorCode alongside the human-readable error message. The errorCode appears on both the Get Generation response (GET /v2/generate/{id}) and the webhook payload delivered when a job finishes.

Branch your error handling on errorCode, not on the error string. The error message is meant for humans and may be reworded over time; the errorCode is a stable identifier you can safely switch on in code.

A failed generation looks like this:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "FAILED",
  "error": "The provided audio exceeds the maximum allowed length.",
  "errorCode": "generation_audio_length_exceeded"
}

Error responses on request endpoints (assets, voices, TTS, and submit-time generate rejections) carry the same machine-readable shape, with two optional extras: field names the request field that caused the failure (for example voiceId or input[].assetId), and docsUrl links to the relevant documentation page. Unhandled 500s include a requestId you can give to support, alongside errorCode: internal_error:

{
  "statusCode": 422,
  "errorCode": "voice_not_found",
  "message": "Voice with ID \"abc\" not found. Please verify the voice ID is correct.",
  "suggestion": "List valid voice ids via GET /v2/voices. Cloned voice ids are UUIDs scoped to the organization that created them.",
  "field": "voiceId"
}

Look up any code with the error catalog

GET /v2/errors returns the full catalog of error codes — generation codes plus the API request codes below — as an array of { code, message, suggestion } objects. The endpoint is unauthenticated — no x-api-key header is required — so you can resolve any errorCode to its meaning and a suggested fix at runtime.

curl https://api.sync.so/v2/errors

A typical entry looks like this:

{
  "code": "generation_audio_length_exceeded",
  "message": "The provided audio exceeds the maximum allowed length.",
  "suggestion": "Trim or split your audio so each generation is under 300 seconds (5 minutes)."
}

Read and resolve an error code

When a generation fails, read its errorCode and look it up in the catalog returned by GET /v2/errors.

# 1. Fetch the failed generation
curl https://api.sync.so/v2/generate/550e8400-e29b-41d4-a716-446655440000 \
     -H "x-api-key: <SYNC_API_KEY>"
# 2. Look up the returned errorCode in the catalog (no auth required)
curl https://api.sync.so/v2/errors

Submit-Time Validation Errors

Some requests are rejected at submit time — the API responds with an error on the request itself, before any render starts, instead of accepting the job and failing it later. These rejections return an HTTP status and a machine-readable errorCode in the response body, so you can correct the request and resubmit without wasting a generation.

StatusError CodeCauseResolution
400invalid_generation_idThe id passed to GET /v2/generate/{id} is not a UUID.Use the id returned by POST /v2/generate.
400unsupported_generation_id_formatThe id passed to GET /v2/generate/{id} uses a provider:id format from another system.Use the plain UUID returned by POST /v2/generate.
402generation_plan_duration_exceededThe output duration exceeds your plan’s per-generation limit. This is sync_mode-aware — cut_off clips the output to the shorter of the audio and video tracks before the limit is checked.Upgrade your plan for a longer limit, use a sync_mode (such as cut_off) that shortens the output, or trim the longer input track.
404generation_not_foundThe id passed to GET /v2/generate/{id} is a valid UUID but no generation matches it in your organization.Check the id, and make sure you’re using the same API key (organization) that created the generation.
409generation_conflictThe controller rejected a duplicate internal backend submission. Public creates accept an optional organization-scoped Idempotency-Key; a generation ID is still server-assigned.Do not blindly retry an ambiguous network failure; confirm the submission outcome before retrying.
409DUPLICATE_SUBMISSIONAn API-key request without Idempotency-Key is identical to one your organization sent in the last 60 seconds, and that original has not failed. No new generation is created.Poll the returned generationId. To create identical generations on purpose, send a unique Idempotency-Key with each one. See Requests without a key.
422invalid_asset_id_formatAn input[].assetId is not a valid UUID.Use the id returned by POST /v2/assets, or provide a url instead.
422asset_not_foundAn input[].assetId doesn’t resolve to an asset your key can access.Use an asset id from your organization (GET /v2/assets); ids from other organizations are not visible.
422generation_input_asset_type_mismatchAn asset’s actual type doesn’t match the input slot it was supplied to (for example, an audio asset placed in a video slot).Make sure each input’s type matches the asset you’re passing, and that the asset is the media kind that slot expects.
422generation_input_too_many_visualThe request contains more than one visual input — only a single video or image is allowed per generation.Send exactly one video or image input.
422generation_input_segments_invalidThe segments array is invalid: segments overlap, a segment’s startTime is greater than its endTime, or two segments reuse the same refId. It’s also returned for an invalid lipsync: false or outputAudio request, for example when every segment sets lipsync: false, or several audio inputs are sent without outputAudio.Review your segments: keep them non-overlapping, ensure startTime < endTime, and use a unique refId per segment. For lipsync: false and outputAudio, see Keep segments unlipsynced.
422generation_input_dub_audio_conflictThe request supplies both dubParams and an explicit audio or text input. These are mutually exclusive.Send one or the other: either dubParams (to dub) or an explicit audio/text input — not both.
422cost_estimate_unavailableEstimate Cost (POST /v2/generations/estimate) could not return a price. No generation is created. Request-field validation returns 400.Check that duration and optional fps are finite, positive numbers. If valid inputs still fail, retry later or contact support with the request ID.
429concurrency_limit_reachedYou have too many generations in progress for your plan’s concurrency limit.Wait for in-flight generations to finish, or upgrade your plan for higher concurrency. See Rate Limits.
429rate_limit_exceededYour per-key request rate was exceeded (for example, on TTS, voice clone, or upload requests).Slow your request rate and implement exponential backoff. See Rate Limits.
503generation_media_probe_unavailable / generation_media_probe_timeoutAn input-media check was unavailable or timed out.Retry with backoff; verify the media host is reachable. Include the request ID when contacting support.
503controller_unavailable / controller_dependency_errorThe generation service (or one of its dependencies) is temporarily unavailable at submit time.For a keyed create, retry with the same key and inputs, honoring Retry-After. For an unkeyed create, confirm acceptance before resubmitting.
503generation_admission_pausedNew generation requests are temporarily paused for maintenance. The request is rejected before any work starts. Generations already accepted keep processing, and you can still check their status.Retry after the Retry-After interval. For a keyed create, keep the same Idempotency-Key and inputs.
503generation_admission_unavailableThe API can’t confirm that new generation requests are being accepted, so it rejects the request before any work starts.Retry after the Retry-After interval. For a keyed create, keep the same Idempotency-Key and inputs.
504controller_timeoutThe generation service took too long to accept the job.For a keyed create, retry with the same key and inputs, honoring Retry-After. For an unkeyed create, confirm acceptance before resubmitting.

A submit-time error returns errorCode on the HTTP response. Validation failures can precede generation creation, but an uncertain submission may already have a generation. Poll generationId when provided and follow the idempotency recovery guidance before retrying.

Rate-limit and dependency errors (429/503/504) also mirror their retry guidance into headers: Retry-After (seconds), and for concurrency 429s, X-Sync-Concurrency-Limit and X-Sync-Active-Generations.

API Request Error Codes

Beyond generation failures, the assets, voices, TTS, and generation download endpoints return their own stable errorCode values on error responses. Where applicable the body also carries field (the request field at fault) and docsUrl (a link to the relevant docs page). All of these appear in the error catalog (GET /v2/errors).

Assets

StatusError CodeCauseResolution
422project_not_foundThe projectId doesn’t exist in your organization (wrong org, deleted, or mistyped).Omit projectId, or use a project id that belongs to your organization.
404asset_not_foundNo asset exists with that id in your organization.Use an asset id returned by POST /v2/assets or GET /v2/assets. Asset ids from another organization are not visible.
403asset_forbiddenYou can view this asset but lack permission to modify or delete it.Only the asset owner or an organization admin/owner can modify it.
422invalid_asset_id_formatAn assetId (including input[].assetId on generate) is not a valid UUID.Use the id returned by POST /v2/assets, or provide a url instead.
422uploaded_file_not_foundNo file bytes were found at the pre-signed upload URL.PUT the file to the uploadUrl from POST /v2/assets/upload before registering the asset.
422file_not_in_org_storageThe URL you registered is not in your organization’s sync. labs storage.Upload via POST /v2/assets/upload first, then register the returned url.
422file_size_exceeds_plan_limitThe file exceeds your plan’s maximum size.Upload a smaller file or upgrade your plan.

Voices and TTS

StatusError CodeCauseResolution
422 / 404voice_not_foundThe voiceId doesn’t resolve to a premade or cloned voice in your organization. Returned as 422 on POST /v2/tts and generation text inputs, 404 on GET /v2/voices/{id} and DELETE /v2/voices/{id}.List valid ids via GET /v2/voices. Cloned voice ids are UUIDs scoped to the organization that created them.
400 / 422voice_verification_requiredThe selected voice needs ElevenLabs verification before it can be used for synthesis. Returned on POST /v2/tts and generation text inputs — normally 422 from the pre-synthesis check, or 400 when that check was unavailable and the voice is rejected during synthesis.If the voice is from your own connected ElevenLabs account, complete verification in ElevenLabs (linked under Settings > Integrations). Otherwise, choose another voice, or contact Sync support for a Sync-managed voice.
400 / 422voice_blockedElevenLabs has blocked the selected voice. Returned on POST /v2/tts and generation text inputs — normally 422 from the pre-synthesis check, or 400 when that check was unavailable and the voice is rejected during synthesis.Choose another voice — a blocked voice can’t be used for synthesis. If it’s from your own connected ElevenLabs account (Settings > Integrations), contact ElevenLabs. Otherwise, for a Sync-managed voice, contact Sync support.
400voice_access_deniedElevenLabs denied access to the selected voice — a generic access denial, not specifically a verification or block state. Surfaces only during synthesis on POST /v2/tts and generation text inputs.Choose another voice. If the voice is from your own connected ElevenLabs account (Settings > Integrations), check its access settings in ElevenLabs; otherwise, for a Sync-managed voice, contact Sync support.
422voice_sample_not_accessibleThe clone sample asset was not found or is not accessible.Use an audio or video asset id from your organization.
422voice_sample_type_unsupportedThe clone sample asset is not audio or video.Clone from an AUDIO or VIDEO asset.
422voice_sample_upload_requiredThe clone sample url is not hosted in sync. labs storage.Upload via POST /v2/assets/upload first, then clone from the returned assetId or url.
422voice_sample_extraction_failedNo audio track could be extracted from the video sample.Check the video has an audio track and is a supported format.
400voice_sample_too_shortThe sample is too short to clone from.Use a longer sample with clear speech (ideally 30+ seconds).
400voice_sample_invalidThe sample could not be processed, or the same sample was added more than once.Use a valid audio file with clear speech, and remove any duplicate sample.
403voice_clone_limit_reachedYour plan’s voice clone slots are all in use.Delete a voice via DELETE /v2/voices/{id} or upgrade your plan.
429voice_clone_busyAnother shared voice clone is reserving provider capacity.Honor Retry-After and retry after the indicated delay.
413voice_sample_source_too_largeThe video source exceeds the 1 GiB clone-preparation limit.Trim the video or use a smaller source.
409voice_name_conflictYou already have a voice with this name.Choose a different name, or delete the existing voice via DELETE /v2/voices/{id} first.
400elevenlabs_api_key_invalidYour connected (bring-your-own) ElevenLabs API key is invalid or revoked.Reconnect a valid key in Settings > Integrations, or remove it to fall back to the shared voices.
402elevenlabs_quota_exceededYour own ElevenLabs account’s quota is exhausted.Check your ElevenLabs subscription, or wait for its quota to reset.
503 / 504elevenlabs_service_unavailableThe ElevenLabs voice service is temporarily unavailable. Returned as 504 for provider timeouts, and 503 for other provider outages on POST /v2/tts and unkeyed generation text inputs. Keyed uncertain outcomes use IDEMPOTENCY_OUTCOME_UNKNOWN.Retry the request with backoff. If it keeps failing, contact support with the request id.

Downloads

GET /v2/generations/{id}/download returns a URL for downloading a completed generation’s output. Missing, deleted, or out-of-organization generations return generation_not_found (404), as covered above. A missing, invalid, or revoked API key returns 401, and a non-UUID id returns 400. The download-specific codes are:

StatusError CodeCauseResolution
409generation_not_readyThe generation is still pending or processing, so its output is not ready to download.Poll GET /v2/generate/{id} until it reports COMPLETED, then request the download URL again.
422generation_not_downloadableThe generation failed or was rejected, so it has no output to download.Inspect the generation’s status and error with GET /v2/generate/{id}; fix the input and resubmit if needed.
404generation_output_unavailableThe generation has no eligible output reference, or the stored output file is missing.This endpoint does not recreate outputs. Contact support if a completed generation is missing its output.
503generation_download_unavailableThe download URL could not be prepared.Retry with exponential backoff. If it keeps failing, contact support with the request id.

Batch upload capacity

A multipart batch upload can return 503 with errorCode: upload_capacity_unavailable. No batch was created. Retry the same request after the number of seconds in Retry-After. You can also submit records as a JSON rows body.

Audio trims

POST /v2/audio-trims and GET /v2/audio-trims/{id} prepare a shorter audio asset for a partial video. These codes aren’t in the error catalog.

StatusError CodeCauseResolution
422audio_trim_source_not_hostedThe audio is hosted outside sync. labs storage.Upload the audio with POST /v2/assets/upload, then trim it by assetId.
422audio_trim_source_not_allowedThe sourceUrl is in sync. labs storage, but not in your organization’s storage.Trim audio that belongs to your organization, or upload it with POST /v2/assets/upload and trim it by assetId.
429audio_trim_rate_limitedYour organization already has 4 trims in progress, or started 60 in the past hour.Wait for a trim in progress to finish, then retry.

A trim that can’t decode or cut the audio ends with status: failed and errorCode: audio_trim_failed on GET /v2/audio-trims/{id}. Check that the source is a readable audio file, then start a new trim with a new Idempotency-Key.

Reusing an Idempotency-Key with a different body returns 409. A missing Idempotency-Key, or one that isn’t 1–128 characters from [A-Za-z0-9._~-], returns 400. An audio source or trim that doesn’t exist or that you can’t access returns 404. Upload external sources first and trim them by assetId.

Rejected and failed generations

REJECTED and FAILED are terminal statuses. Inspect errorCode and error on the generation response or webhook. REJECTED means the request or account needs a correction before another attempt. FAILED means processing stopped because of an operational error. Follow the recovery for the returned code, and contact support if it persists.

A request refused before a generation exists returns its error on the HTTP response. Stop polling when a generation reaches either terminal status. For retries, follow Idempotent requests.

What do Sync Labs API error codes mean?

Here’s a comprehensive list of Sync Labs 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 model 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.

generation_input_audio_invalid

Message: “The provided audio file has invalid metadata.”

Description: This error occurs when the audio file contains metadata that cannot be properly parsed or validated. Unlike generation_media_metadata_missing (which indicates missing metadata), this error means metadata is present but malformed, corrupted, or contains invalid values. Typical causes are corrupted audio files, damaged headers, or files from tools that produce non-standard metadata.

Resolution:

  1. Re-encode your audio file using a standard tool like FFmpeg to ensure proper metadata formatting: 
    ffmpeg -i input.wav -c:a pcm_s16le output.wav
  2. Verify that your audio file opens and plays correctly in a media player.
  3. Check that the audio file has not been corrupted during download or transfer.
  4. If the issue persists, try converting your audio to a different supported format (WAV, MP3, OGG, FLAC) and re-submit.

generation_input_face_selection_invalid

Message: “We could not use the selected speaker face for this video. Please select the face again or try auto-detect.”

Description: This error occurs when the manually selected speaker face cannot be used for the generation. The selected face may not be detected in the video, the supplied face coordinates may fall outside the video frame, or the active-speaker selection may be invalid.

Resolution:

  1. Re-run face detection and select the speaker again, making sure the face is clearly visible in the chosen frame.
  2. Verify that any manually supplied coordinates or bounding boxes fall within the video’s dimensions.
  3. Alternatively, turn off manual speaker selection to let the system auto-detect the active speaker, then resubmit.

Batch API Errors

Batch validation errors are 400 responses with only a message; they have no errorCode. Access, plan, and capacity refusals use the codes below. Dry runs require the same organization approval and plan as batch creation.

Batch access is not enabled (batch_access_not_enabled)

Status: 403

Description: Your organization has not been approved to create batches. Access is disabled by default, including for new Scale subscriptions. Dry runs require the same approval. Existing batches continue processing and remain readable when creation access is removed.

Resolution: Contact support@sync.so to request organization access. Upgrading a plan does not enable access automatically.

Batch needs the Scale plan (plan_feature_unavailable)

Status: 402

Description: The Batch API requires organization approval and a Scale plan or above (Scale, Enterprise, partner and program plans). Other plans and free accounts cannot create batches. The body carries requiredPlan and a billingUrl: requiredPlan is scale, or enterprise on credit plans, because no self-serve credit plan includes batch.

Resolution:

  1. Upgrade to Scale, or contact sales about Enterprise, and request organization approval to use the Batch API.
  2. To run a few generations at once without batch, send POST /v2/generate requests in parallel within your concurrency limit. See When to use batch, and when not to.

Batch concurrency limit (concurrency_limit_reached)

Status: 429, with Retry-After and X-Sync-Concurrency-Limit headers

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: You already run as many batches as your plan allows. Each active batch holds one slot of a batch limit equal to your plan’s concurrency limit. The body carries activeBatches, concurrencyLimit and retryAfterSeconds.

Resolution:

  1. Wait retryAfterSeconds, or until an active batch finishes.
  2. Check your active batches with GET /v2/batch.

Batch validation messages

StatusMessageFix
400Input file is required / Input file cannot be emptySend the JSONL in the input field, or use a JSON rows body.
400File size exceeds the maximum limit of 5MBThe batch is over 5 MB as sent or after its dialogue edit rows are expanded. Split the records into several batches.
400Number of records exceeds the maximum limit of NSend at most N records. N is 500 by default, or your account’s own limit.
400Input file must contain at least N records. Found X record(s).A batch needs at least 20 records; send fewer than 20 with POST /v2/generate.
400Invalid JSON at line X: ...Make each line one valid JSON object.
400Duplicate request_id found at line X: ...Use a unique request_id for each record.
400Record at line X: request_id is required / payload is requiredAdd the missing field.
400Record at line X: endpoint must be '/v2/generate'Set "endpoint": "/v2/generate".
400Record at line X: Invalid payload - ...Fix the payload so it is a valid POST /v2/generate body.

Line numbers count non-empty records; with a JSON rows body, line N is rows[N-1].

Dialogue edit row refusals

Example: {"statusCode": 422, "errorCode": "dialogue_edit_not_found", "lineNumber": 3, "message": "Record at line 3: The dialogue edit was not found in this organization."}

Description: Batch rows that carry dialogueEdit (early access) are checked at submit, including with dry_run. If a row cannot be rendered, no batch is created. The response carries the same errorCode that POST /v2/generate returns for that preview, such as dialogue_edit_not_found, dialogue_edit_not_completed, dialogue_edit_source_mismatch, or dialogue_edit_batch_mixed_sources, plus the lineNumber of the first failing row. Line numbers count non-empty records; with a JSON rows body, line N is rows[N-1]. Other batch record errors, such as invalid JSON, give the line only in message.

Resolution:

  1. Find the row at lineNumber and fix it as described in Dialogue edit refusals.
  2. Validate again with dry_run until the response is {"status": "VALIDATED"}.

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.

Report an unclear error or a workaround

If an error didn’t say what to fix, a result was wrong, or you needed a workaround, report it with Submit Feedback (POST /v2/feedback). Send one report per problem with a kind (confusing_error, bug, missing_capability, workaround, docs or other) and a message of up to 4,000 characters that includes the exact error text. Add the errorCode and generationId when you have them. The sync. team reviews reports daily. The call returns 202 with a reference id, doesn’t change or retry any job, and is limited to 30 reports per minute. The MCP server exposes the same report as the feedback_send tool.

curl -X POST https://api.sync.so/v2/feedback \
  -H "x-api-key: $SYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "confusing_error",
    "severity": "major",
    "message": "POST /v2/generate returned generation_input_video_inaccessible for a presigned URL that plays in a browser.",
    "errorCode": "generation_input_video_inaccessible",
    "generationId": "6533643b-acbb-4c4f-a5b3-5ba2e5ab6b5f"
  }'

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 Labs 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, poll its existing ID or contact support. Do not create a replacement just because it is still pending.

After a generation ends FAILED or REJECTED, retry with the same key and inputs: the retry starts a new generation, admitted and billed like a first request. For a timeout or unknown submission outcome, keep the original key and inputs; do not start a replacement. See Idempotent Requests.