Public API errors
Every error response is an RFC 9457 Problem Details document (application/problem+json):
codeis the stable machine string to branch on.typelinks to this page (https://developers.synthesia.io/docs/errors#<code>) — it’s documentation, not an identifier, and its URL may change.detailis human-readable and may change without notice; each code below shows example messages ({braces}mark request-specific values).requestId(also theRequest-Idheader) 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 codeinternal. Handle any response you don’t recognize by its HTTP status.
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 thatmediaAssetIdis 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.
mediaUrlmust 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 withGET /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
autois 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
sourceIddoes 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
mediaAssetIdfailed to upload or was rejected. Upload it again and use the newmediaAssetId.
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
mediaAssetIdis 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.