For Developers
DashboardLog InGet an API key
Using the API

Troubleshooting

Find the cause of common API failures and how to fix them.

Start with the status code and code, then find the matching section. If you contact support, include requestId from the response.

Authentication

401 UNAUTHORIZED

The key is missing, malformed, wrong, revoked or expired. All of these return the same response.

  • Check the header name is SYNTH_API_KEY, including the underscore. Some proxies and gateways drop headers with underscores, so check any proxy between your code and our API.
  • Copy the whole key again from Settings > API Keys, and check for added spaces, quotes or line breaks.
  • Check the key's status in the dashboard. A revoked or expired key can't come back, so create a new one.

403 FORBIDDEN

The key lacks the permission this route needs, or its owner can't do this.

  • Dashboard keys have read and write, so DELETE routes return this error. See Permissions.
  • Webhook settings, webhook deliveries and custom functions need write, even to read them.
  • If the key's owner is a viewer, write requests return this error whatever the key's permissions. Use a key created by a workspace admin.

429 with a bad key

Your IP address sent too many missing or bad keys. Fix the key, wait for Retry-After, then retry. See Missing or bad keys.

503 SERVICE_UNAVAILABLE with Retry-After: 5

We couldn't check the key. Your key is fine, so retry after the wait and don't replace it.

Requests

404 NOT_FOUND

Check the path and the ID. The base URL includes /api, so the full address is https://backend.synthesys.app/api/v1/agents. An ID from another account also returns 404.

400 VALIDATION_ERROR with details.issues

A field failed validation, and each issue's path names it. Common causes:

  • limit is above 100 or below 1, or isn't digits only.
  • A date isn't valid ISO 8601. Use 2026-10-31 or 2026-10-31T12:00:00Z, and encode + as %2B in a query string.
  • search is only *. Leave it out to list everything.
  • POST /v1/calls used agent_id instead of agentId. That route uses camelCase, while contacts use snake_case such as first_name.
  • An ID such as agentId or a filter such as agent_id isn't a valid UUID.
  • A phone number isn't dialable. It must be valid for its country.

400 VALIDATION_ERROR with no issues

The request failed before any field was checked. The JSON is malformed, the Content-Type header is missing, the body is nested too deeply, or it contains invalid text.

413 PAYLOAD_TOO_LARGE

The body is over 256 KB, or over 2 MB when saving custom functions. See Body limits.

415 UNSUPPORTED_MEDIA_TYPE

Send Content-Type: application/json.

409 CONFLICT

The message says which case applies:

  • A duplicate. A contact has that phone number or email, or a knowledge base or audience has that name. Find the existing record and update it.
  • Settings changed. You tried to save post-call webhook or custom function settings using an old version. Read them again, then retry with the new version.

CORS errors in the browser

The API only accepts browser requests from Synthesys's own sites. Call it from your server. This also keeps your key out of the browser.

Calls

400 MISSING_IDEMPOTENCY_KEY

POST /v1/calls needs an Idempotency-Key header. See Idempotency.

409 IDEMPOTENCY_KEY_REUSED

You used this key with a different body, so nothing was placed. Send a new key for a new call. A key must stay paired with exactly one request body.

409 REQUEST_IN_PROGRESS

The first request with this key is still running. Wait a moment, then retry with the same key.

422 from POST /v1/calls

The agent or phone number isn't ready to call, and nothing was queued. Read details.action, and see the full list of codes. Most often, the phone number isn't assigned to the agent you sent. Fix that in the dashboard, then retry with the same key.

429 EXECUTION_CAPACITY_EXCEEDED

You have 100 calls queued or in progress. Retry after Retry-After, which is 60 seconds, with the same key.

201 returned, but no call happened

Read the call with GET /v1/calls/{id}, using the callId from the response.

  • queued: the call is waiting. The most common reason is calling hours. It can wait overnight, up to 35 hours.
  • dialing or in_progress: the call is going out.
  • failed: failure_code and failure_message say why. See Failure codes.

503 from POST /v1/calls with Idempotency-Replay: true

The call couldn't be queued the first time, and the same key returns that same answer for 24 hours. Send a new key to try again. If Idempotency-Replay isn't set, retry with the same key.

Finding the call log for a specific call

List GET /v1/call-logs for the agent, and find the log whose directCallId matches your callId. The log appears after the call has run. See Get transcripts and recordings.

The recording's status isn't ready, or it has no audio file yet. Check again shortly.

recording_url is null

This is expected. Those fields are always null in API responses. Use GET /v1/recordings/{id}/download-url to get a signed link. See Recordings.

Limits

429 RATE_LIMIT_EXCEEDED

The key used its per-minute or per-day allowance. Wait for Retry-After. If it is 3600, the key hit its daily limit. See Rate limits.

Server errors

500 INTERNAL_ERROR

Retry with backoff. If it continues, contact support with the requestId.

502, 503 or 504

A dependency failed or timed out. Retry with backoff, and wait for Retry-After when it's present.