Skip to navigation

Public API errors

Every error response is an RFC 9457 Problem Details document (application/problem+json):

  • code is the stable machine string to branch on. type links to this page (https://developers.synthesia.io/docs/errors#<code>) — it’s documentation, not an identifier, and its URL may change.
  • detail is human-readable and may change without notice; each code below shows example messages ({braces} mark request-specific values).
  • requestId (also the Request-Id header) identifies the request in Synthesia’s logs — include it when contacting support.
  • New codes may appear over time; a rare unmapped 4xx surfaces as http_<status>, and an unexpected 5xx keeps its status with code internal. Handle any response you don’t recognize by its HTTP status.
Statuscodetitle
400bad_requestBad request
400 / 422invalid_target_languageInvalid target language
400validation_errorInvalid request
401api_key_expiredAPI key expired
401unauthenticatedUnauthenticated
402feature_not_in_planFeature not in plan
402no_creditNo credit
402payment_requiredPayment required
402quota_exceededQuota exceeded
402user_credit_limit_reachedUser credit limit reached
403client_disabledClient disabled
403connection_requiredConnection required
403forbiddenForbidden
403insufficient_scopeInsufficient scope
403organization_disabledOrganization disabled
403scope_not_availableScope not available
403workspace_requiredWorkspace required
404not_foundNot found
404unknown_referenceUnknown reference
405method_not_allowedMethod not allowed
409configuration_not_publishedConfiguration not published
409conflictConflict
409deployment_disabledDeployment disabled
409localization_import_failedLocalization import failed
409media_asset_failedMedia asset failed
409media_asset_not_readyMedia asset not ready
413payload_too_largePayload too large
415unsupported_media_typeUnsupported media type
422configuration_invalidConfiguration invalid
422moderationModeration
429concurrency_limitConcurrency limit exceeded
429rate_limitedRate limit exceeded
500internalInternal error
500processing_errorProcessing error
503admission_unavailableAdmission temporarily unavailable
503capacity_exhaustedPlatform capacity reached
503service_unavailableService unavailable
504timeoutUpstream timeout

bad_request

Bad request — status 400 — type

The request could not be parsed as sent — usually a body that is not JSON. Fix the request before retrying; an unchanged retry fails the same way.

Example detail messages:

  • The request body is missing or null. Send a JSON object.
  • The request body is not valid JSON. Send a JSON object.
  • The request body was not sent as JSON. Set the Content-Type header to application/json.

invalid_target_language

Invalid target language — status 400, 422 — type

A target language can’t be used for this localization. Pick one from GET /api/localizations/languages?supports=dubbing_target; an unchanged retry fails the same way.

Example detail messages:

  • A target language is not supported for localization.
  • A target language is not supported for this localization.

validation_error

Invalid request — status 400 — type

One or more request fields were rejected. Fix the fields detail lists and resend; an unchanged retry fails the same way.

For a rejected request body, detail lists each rejected field as path: message, joined with ; ; other validation denials use the standalone messages below.

Example detail messages:

  • A locale could not be added.
  • Could not establish a media connection to the LiveKit server at livekitUrl. Its WebRTC ports (UDP/TCP) or a TURN server must be reachable from the internet; HTTP-only tunnels such as Cloudflare quick tunnels or ngrok carry signalling but not media.
  • Locales can’t be added to this localization. If you asked for lip-sync, your plan may not include it: retry with lipsyncEnabled: false. Otherwise a language is no longer offered, its import failed, or its workspace can’t dub it; GET /localizations/{localization_id} shows whether it failed.
  • Name the workspace this call acts in.
  • Not a valid {concept} id.
  • One or more fields were rejected.
  • The localization could not be created. If you asked for lip-sync, your plan may not include it: retry with lipsyncEnabled: false. Otherwise check that mediaAssetId is a video that uploaded correctly and that every language is still offered, or ask a workspace admin whether your workspace can dub.
  • The request was rejected. mediaUrl must be a presigned S3 URL (other URLs are not supported yet) for a video within the size limit.
  • The supplied livekitToken cannot be used to join the room. It must be an unexpired LiveKit access token, signed with the API key of the LiveKit server at livekitUrl, granting roomJoin to the room, with its lk.publish_on_behalf attribute set to your agent’s participant identity.
  • Translations are not supported yet.
  • body.sourceLanguage: Not a language you can localize from, or auto. List them with GET /localizations/languages?supports=dubbing_source.
  • body.sourceLanguage: Not a language you can localize from. List them with GET /localizations/languages?supports=dubbing_source.
  • query.cursor: Not a valid cursor. Omit it to start from the first page.
  • {field}.formality: Only auto is supported for now.
  • {field}.generate: Dubbing always makes the video; use true.
  • {field}: Not a language you can localize into. List them with GET /localizations/languages?supports=dubbing_target.

api_key_expired

API key expired — status 401 — type

The API key is genuine but past its expiry date. Not retryable with this key — create a new key and use it instead. The WWW-Authenticate: Bearer header carries error="invalid_token".

Example detail messages:

  • Your API key has expired. Create a new key and retry with it.

unauthenticated

Unauthenticated — status 401 — type

The request carried no usable API key. Send your key as Authorization: Bearer <key>. An unknown or revoked key is reported only as invalid; an expired key answers api_key_expired instead. The WWW-Authenticate: Bearer header carries realm alone when no key was sent, error="invalid_request" for an Authorization scheme other than Bearer, and error="invalid_token" for a rejected key.

Example detail messages:

  • Invalid API key.
  • Provide your API key in the Authorization header.
  • Provide your application’s OAuth access token in the Authorization header.
  • Unsupported Authorization scheme. Send your API key as ‘Authorization: Bearer <key>’.
  • Unsupported Authorization scheme. Send your application’s OAuth access token as ‘Authorization: Bearer <token>’.

feature_not_in_plan

Feature not in plan — status 402 — type

Your workspace’s plan does not include a feature this endpoint requires; features names it. Not retryable — upgrade the plan or contact your account manager.

Example detail messages:

  • This workspace’s plan does not include the ‘{scope}’ scope.
  • Your plan does not include interactive avatars — upgrade to use this API.
  • Your plan does not include the ‘{feature}’ feature.

no_credit

No credit — status 402 — type

Your workspace has no credit remaining for the metered feature this request consumes. Not retryable until the balance is positive again — top up or upgrade your plan.

Example detail messages:

  • Your plan has no interactive avatar credits. Top up or upgrade to create interactive avatars.
  • Your workspace doesn’t have enough credit to dub this video.
  • Your workspace has no credit remaining for this deployment’s sessions. Top up or upgrade.

payment_required

Payment required — status 402 — type

The request was declined for billing reasons, such as exhausted credits or no valid payment plan. Resolve the billing condition, then retry. Also reported in a failed localization’s error, inside a successful response: there, the workspace has no valid payment plan; create a new localization once it has one.

Example detail messages:

  • Your workspace has no valid payment plan.

quota_exceeded

Quota exceeded — status 402 — type

A usage quota in your plan is used up. Not retryable until your quota is increased or replenished — upgrade your plan or contact your account manager.

Example detail messages:

  • Your session quota is exhausted.

user_credit_limit_reached

User credit limit reached — status 402 — type

You have run out of your monthly credit limit for the metered feature this request consumes, while your workspace still has credit. Not retryable until the limit resets — ask a workspace admin to raise it. Also reported in a failed localization’s error, inside a successful response: create a new localization once the limit is raised or reset.

Example detail messages:

  • You have run out of your monthly credit limit. Ask a workspace admin to raise it, or wait for it to reset.
  • You have run out of your monthly credit limit. Create a new localization once a workspace admin raises it or it resets.

client_disabled

Client disabled — status 403 — type

The access token is valid, but the workspace the call names has AI tool access turned off; detail names the workspace. Keep the access and refresh tokens and do not re-authorize. Ask a workspace admin to turn it on, then retry the same request.

Example detail messages:

  • Workspace {workspace} has AI tool access turned off. Ask a workspace admin to turn it on, then retry the same request; no new authorization is needed.

connection_required

Connection required — status 403 — type

The access token is valid, but the Synthesia account behind it has no active connection for your application: it was never completed, was disconnected, or expired after 30 days without use. Call POST /connections with the same token, then retry. If the token has expired and refreshing it fails, re-authorize the user first.

Example detail messages:

  • This Synthesia account has no active connection for your application. Call POST /connections, then retry.

forbidden

Forbidden — status 403 — type

Your API key is valid but not permitted to do this: for example, your account lacks the permission or your plan doesn’t include the option. detail, when present, says which. If you believe you should have access, check with your workspace admin.

Example detail messages:

  • This API key acts only in its own workspace, and the {noun} is in another one.
  • This API key acts only in workspace {workspace}. Name that workspace, or leave the workspace out.
  • This endpoint accepts an OAuth access token issued to your application, not an API key.
  • Your plan doesn’t include one of these languages, or you can’t create videos in this workspace.
  • Your plan doesn’t include one of these languages, or you can’t edit this localization.

insufficient_scope

Insufficient scope — status 403 — type

Your API key or access token does not carry the scope this endpoint requires; detail names it, as does scope in the WWW-Authenticate: Bearer error="insufficient_scope" header. Use or create a key with that scope, or re-authorize to request it — retrying with the same credential fails the same way. A stronger scope on the same resource also works (:write satisfies :read); Scopes lists every scope and the endpoints that need it.

Example detail messages:

  • Your API key does not have the ‘{scope}’ scope this endpoint requires.
  • Your access token does not have the ‘{scope}’ scope this endpoint requires.

organization_disabled

Organization disabled — status 403 — type

The access token is valid, but the user’s Synthesia organization has not enabled the integration for your application. Keep the access and refresh tokens and do not re-authorize: consent was given and only the organization’s setting blocks the call. Ask the user to contact their Synthesia admin, then retry the same request once it is enabled.

Example detail messages:

  • This user’s Synthesia organization has not enabled the integration for your application. Ask a Synthesia admin in the organization to enable it, then retry the same request; no new authorization is needed.

scope_not_available

Scope not available — status 403 — type

The access token carries the scope this endpoint requires, but the application is not allowed to use it; detail names it. Keep the access and refresh tokens and do not re-authorize: a new consent returns the same scope and fails the same way. Contact the application’s developer. When the workspace’s plan is what lacks the scope, the answer is feature_not_in_plan instead.

Example detail messages:

  • Your access token has the ‘{scope}’ scope, but this application may not use it.

workspace_required

Workspace required — status 403 — type

The access token is valid, but the user has no Synthesia workspace and one cannot be created for them from this call. Keep the access and refresh tokens and do not re-authorize. Ask the user to sign in to Synthesia and create a workspace, then retry the same request.

Example detail messages:

  • Workspace setup is not available for this account. Sign in to Synthesia to create a workspace, then retry the same request; no new authorization is needed.

not_found

Not found — status 404 — type

Nothing exists at this URL that your credential can reach. Check the path, any resource id in it or the workspace the call names, and that the credential belongs to the resource’s workspace.

Example detail messages:

  • No localization with this id.
  • There’s no {noun} {resource_id} that you can access.
  • Workspace {workspace} does not exist or this user is not a member of it.

unknown_reference

Unknown reference — status 404 — type

An id in the request body doesn’t match anything your API key can access. Check the id, and that you’re using a key from the workspace the resource belongs to.

Example detail messages:

  • No video you uploaded has this mediaAssetId.
  • One or more of avatarIds does not exist or is not accessible.
  • The sourceId does not match an avatar you can access.
  • deploymentId does not exist, is not an API deployment, or is not in your workspace.

method_not_allowed

Method not allowed — status 405 — type

The URL exists, but not for this HTTP method. The Allow header lists the methods it supports.

configuration_not_published

Configuration not published — status 409 — type

The deployment’s configuration has no live version. Publish the configuration in Studio, then retry.

Example detail messages:

  • The deployment’s configuration has no live version. Publish it in Studio, then retry.

conflict

Conflict — status 409 — type

The request conflicts with the resource’s current state. Fetch the resource, reconcile, and resend.

Example detail messages:

  • The LiveKit room was closed or deleted, or the avatar’s participant was removed or replaced by another participant with the same identity, while the session was starting. Retrying against a room that is no longer open fails the same way: start the session in an open room, with a livekitToken for that room, and keep it open until the session starts. If another participant joined with the livekitToken’s identity, give the avatar an identity of its own.
  • The localization is still importing its video. Retry once its status is no longer queued.

deployment_disabled

Deployment disabled — status 409 — type

The deployment is paused, so it starts no sessions. Not retryable until it is turned back on in Studio.

Example detail messages:

  • The deployment is paused. Turn it back on in Studio, then retry.

localization_import_failed

Localization import failed — status 409 — type

The localization’s video failed to import, so it can’t take locales. Not retryable: create a new localization; GET /api/localizations/{localization_id} shows why the import failed.

Example detail messages:

  • The localization’s video failed to import, so it can’t take locales. Create a new localization; GET /localizations/{localization_id} shows why it failed.

media_asset_failed

Media asset failed — status 409 — type

The video behind mediaAssetId failed to upload or was rejected, so it can’t be localized. Not retryable with this id: upload the video again and use the new mediaAssetId.

Example detail messages:

  • The video with this mediaAssetId failed to upload or was rejected. Upload it again and use the new mediaAssetId.

media_asset_not_ready

Media asset not ready — status 409 — type

The video behind mediaAssetId is still uploading or processing, so it can’t be localized yet. Retry with backoff; the same request succeeds once the video is ready.

Example detail messages:

  • The video with this mediaAssetId is still uploading or processing. Retry once it’s ready.

payload_too_large

Payload too large — status 413 — type

The request body exceeds the size this endpoint accepts. Reduce the payload and resend.

unsupported_media_type

Unsupported media type — status 415 — type

The request’s Content-Type is not one this endpoint accepts. Send the body as application/json unless the endpoint documents otherwise.

configuration_invalid

Configuration invalid — status 422 — type

The deployment’s live configuration cannot start a session, for example because of a voice or avatar that cannot be used. Not retryable as is. Fix and republish the configuration in Studio.

Example detail messages:

  • The deployment’s live configuration cannot start a session. Fix and republish it in Studio.

moderation

Moderation — status 422 — type

The video failed content moderation, so it won’t be localized. Reported in a failed localization’s or locale’s error, inside a successful response; status (422) classifies the failure. Not retryable with the same video.

Example detail messages:

  • The video failed content moderation.

concurrency_limit

Concurrency limit exceeded — status 429 — type

Your plan’s ceiling on concurrently running sessions is reached. Retryable — end an active session or wait for one to finish, honoring Retry-After when present.

Carries Retry-After when Enact sends a wait interval. When known, detail leads with the caller’s plan numbers and keeps the guidance to end or wait for a session.

Example detail messages:

  • Too many sessions are running concurrently for your plan. End an active session or wait for one to end.

rate_limited

Rate limit exceeded — status 429 — type

Too many requests in the current window. Retryable — back off for the Retry-After interval, then resend the same request.

The facade’s own denials carry RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset-At and Retry-After headers; a domain’s 429 carries at most Retry-After.

Example detail messages:

  • Too many requests. Retry after the interval in the Retry-After header.

internal

Internal error — status 500 — type

Something unexpected failed on Synthesia’s side. Usually safe to retry; for a request that creates a resource, check whether the operation went through first. If it persists, contact support and quote the requestId.

Example detail messages:

  • An unexpected error occurred.
  • The session could not be started, and retrying will not help. Contact support with the request id.

processing_error

Processing error — status 500 — type

Localization failed while processing the video. Reported in a failed localization’s or locale’s error, inside a successful response; status (500) classifies the failure. For a localization, it can also mean the plan doesn’t include lip-sync or one of the target languages, or the workspace can’t dub. If you requested lip-sync, retry without it or check your plan includes it. Otherwise create a new localization; if it keeps failing, contact support and quote the localization id.

Example detail messages:

  • Localization failed while processing the video. It can also mean your plan doesn’t include lip-sync or one of the target languages, or your workspace can’t dub.
  • This language failed while its video was being made. Create a new localization to retry it; if it keeps failing, contact support and quote the localization id.

admission_unavailable

Admission temporarily unavailable — status 503 — type

A billing or rate decision this request needs could not be obtained, so it was denied rather than admitted unchecked. Transient — retry with backoff, honoring Retry-After when present.

Example detail messages:

  • Admission is temporarily unavailable. Retry shortly.

capacity_exhausted

Platform capacity reached — status 503 — type

Shared platform capacity is momentarily full. This is not an outage and not your plan’s limit: it can happen on your first request, before you reach your plan’s documented rate. Retry after the Retry-After interval, treating it as a minimum and adding a little random jitter so retries from many clients don’t arrive at the same instant.

Example detail messages:

  • Session starts are briefly limited by shared platform capacity. Retry after the interval in the Retry-After header.
  • Shared platform capacity for concurrent sessions is reached right now. Retry after the interval in the Retry-After header.

service_unavailable

Service unavailable — status 503 — type

A service this request needs is temporarily unavailable. Transient — retry with backoff, honoring Retry-After when present and any instruction in detail. If it persists, contact support and quote the requestId.

Example detail messages:

  • Authentication is temporarily unavailable. Retry shortly.
  • Couldn’t look up the {noun}‘s workspace, so the tool didn’t run.
  • Plan features for this request could not be verified. Retry shortly.
  • Temporarily unable to create an interactive avatar. Retry the same request with regenerate off.
  • Temporarily unable to read credits. Retry shortly.
  • Temporarily unable to read the plan. Retry shortly.
  • Temporarily unable to start a session. If you retry, reuse the same livekitUrl and livekitToken.
  • Temporarily unable to start a session. Retry shortly.
  • The session could not be started. Retry shortly.
  • The workspace for this account is not ready yet. Retry after the interval in the Retry-After header.
  • Workspace setup for this account failed. Retry after the interval in the Retry-After header.

timeout

Upstream timeout — status 504 — type

The request did not finish within its deadline. The underlying operation may still have gone through — follow the guidance in detail on how to retry or poll safely, otherwise retry with backoff.

Example detail messages:

  • Authentication is temporarily unavailable. Retry shortly.
  • Plan features for this request could not be verified. Retry shortly.
  • The request did not complete within its {deadline_seconds}s deadline.
  • The session did not start before the deadline. It may still start. If you retry, reuse the same livekitUrl and livekitToken.
  • Timed out reading credits. Retry shortly.
  • Timed out reading the plan. Retry shortly.
  • Timed out waiting for the avatar status. Generation may still be running; repeat the same request with regenerate off to poll.
  • Timed out waiting for the session to start. If you retry, a new session starts. A session that nobody joins ends on its own.
  • Timed out waiting for the session to start. It may still start. If you retry, reuse the same livekitUrl and livekitToken.