Error codes - PolyAI Platform

When a request fails, PolyAI APIs return a structured JSON error response. This page documents the HTTP status codes, error response format, and platform-specific error codes you may encounter. 63 platform error codes span the categories below — jump straight to yours:

Error response format

All API errors return a JSON body with the following structure:

{
  "success": false,
  "error": "Request body failed schema validation.",
  "error_id": "550e8400-e29b-41d4-a716-446655440000",
  "error_code": "SCHEMA_VALIDATION_FAILED",
  "error_message": "Request body failed schema validation.",
  "data": null
}

Field	Type	Description
`success`	boolean	Always `false` for error responses.
`error`	string	Human-readable error message.
`error_id`	string	Unique request identifier from the `X-PolyAI-Correlation-Id` header. Include this when contacting support.
`error_code`	string	Machine-readable error code in `UPPER_SNAKE_CASE`.
`error_message`	string	Human-readable error message.
`data`	null	Always `null` for error responses.

Standard HTTP status codes

These standard codes apply across all PolyAI APIs. Client errors (4xx) mean fix the request; server errors (5xx) mean retry or contact support.

Platform error codes

Expand the category you’re hitting, or use one of the jump links above.

Authentication and authorization

Code	ID	HTTP	Description
`AUTH_USER_NOT_FOUND`	3001	401	User not found in the auth system.
`AUTH_USER_UNAUTHORISED`	3002	401	Invalid credentials or expired session.
`AUTH_USER_INVALID_TOKEN`	3003	401	Token is malformed, expired, or revoked.
`USER_ACCESS_FORBIDDEN`	2	403	User lacks permission for the requested action.
`EXTERNAL_USER_FORBIDDEN`	3	403	External user privilege level is too low.
`ACCOUNT_INSUFFICIENT_PERMISSIONS`	1003	403	User lacks permissions for this account operation.

Conversations

Code	ID	HTTP	Description
`CONVERSATIONS_NOT_FOUND`	5001	404	Conversation ID does not exist.
`CONVERSATIONS_VALIDATION_FAILED`	5002	400	Conversation request body failed validation.
`CONVERSATIONS_RECORDING_NOT_FOUND`	5003	404	Audio recording not found for this conversation.
`GET_CONVERSATIONS_FILTER_PARSE_ERROR`	—	400	Filter expression syntax is invalid.
`GET_CONVERSATIONS_INVALID_SORT_PARAMETER`	—	400	Sort field is not in the allowed set.

Chat

Code	ID	HTTP	Description
`CHAT_DRAFT_NOT_EXIST`	4001	400	The draft you are attempting to chat with does not exist.
`CHAT_TIMEOUT`	4002	400	Chat session exceeded the timeout limit.
`CHAT_DRAFT_DEPLOYMENT_FAILED`	4003	500	Draft auto-deploy failed before the chat could start.
`ChatConversationEnded`	—	410	You sent a message to a conversation that has already ended.

Deployments

Code	ID	HTTP	Description
`DEPLOYMENT_NOT_FOUND`	6001	404	Deployment ID does not exist.
`DEPLOYMENTS_ALREADY_PUBLISHED`	6009	409	Draft is already published to the target environment.
`DEPLOYMENTS_ENVIRONMENT_ALREADY_PUBLISHED`	6002	200	Environment already has this version (idempotent).
`DEPLOYMENTS_VALIDATION_FAILED`	6007	400	Request body validation failed.
`DEPLOYMENTS_INVALID_ENVIRONMENT`	6008	400	Invalid or missing `environment` query parameter.
`ErrPreReleaseNotReady`	—	412	You must deploy to pre-release before promoting to live.

Flows

Code	ID	HTTP	Description
`FLOW_NOT_FOUND`	8001	404	Flow ID does not exist.
`FLOWS_NAME_ALREADY_EXISTS`	8003	409	A flow with this name already exists.
`FLOWS_FUNCTION_NAME_ALREADY_EXISTS`	8004	409	A function with this name already exists in the flow.
`FLOWS_RESERVED_PARAMETER_NAME`	8005	400	You used a reserved parameter name.
`FLOWS_RESERVED_FUNCTION_NAME`	8006	400	You used a reserved function name.

Functions

Code	ID	HTTP	Description
`FUNCTION_NOT_FOUND`	9001	404	Function ID does not exist.
`FUNCTIONS_DEPLOYMENT_HAS_ERRORS`	9004	400	Function code contains errors that prevent deployment.
`FUNCTION_EXECUTION_FAILED`	9006	400	Function encountered a runtime execution error.
`FUNCTION_FAILED_TO_PARSE`	9007	400	Function source code has parse errors.
`FUNCTION_NAME_ALREADY_EXISTS`	9009	409	A function with this name already exists.
`FUNCTIONS_RESERVED_NAME`	9010	400	You used a system-reserved function name.

Knowledge base

Code	ID	HTTP	Description
`KNOWLEDGE_BASE_TOPIC_ALREADY_EXISTS`	11001	409	A topic with this name already exists.
`KNOWLEDGE_BASE_IMPORT_NO_CSV_FOUND`	11002	400	No CSV file found in the import request.
`KNOWLEDGE_BASE_IMPORT_INVALID_TYPE`	11003	415	The uploaded file type is not supported.
`KNOWLEDGE_BASE_IMPORT_MISSING_COLUMNS`	11004	400	Required columns are missing from the CSV import.
`KNOWLEDGE_BASE_TOPICS_INVALID`	11005	400	Topic data failed validation.
`KNOWLEDGE_BASE_RICH_TEXT_INVALID`	11006	400	Rich text markup is malformed or references a missing entity.

Phone numbers and connectors

Code	ID	HTTP	Description
`PHONE_NUMBERS_NOT_FOUND`	14006	404	Phone number does not exist.
`PHONE_NUMBERS_ALREADY_EXISTS`	14007	409	Phone number has already been imported.
`PHONE_NUMBERS_INVALID_PHONE_NUMBER_FORMAT`	14003	400	Number is not in valid E.164 format.
`PHONE_NUMBERS_CONNECTOR_DOES_NOT_EXIST`	14005	404	Referenced connector not found.
`CONNECTORS_NOT_FOUND`	14100	404	Connector ID does not exist.
`CONNECTORS_VALIDATION_FAILED`	14101	400	Connector request body failed validation.

Variants

Code	ID	HTTP	Description
`VARIANTS_BAD_ATTRIBUTES_ERROR`	26001	400	Attribute values do not match the expected schema.
`VARIANTS_DUPLICATE_NAME_ERROR`	26002	409	A variant with this name already exists.
`VARIANTS_REMOVE_DEFAULT_ERROR`	26003	400	You cannot remove the default variant.
`VariantsImportInvalidDelimiter`	—	400	CSV delimiter not recognized.
`VariantImportMissingColumnsHttp`	—	400	CSV is missing required columns.
`VariantImportDuplicateColumnsHttp`	—	400	CSV has duplicate column headers.

Real-time configuration

Code	ID	HTTP	Description
`REAL_TIME_CONFIG_FORBIDDEN_ACCESS`	29001	403	Not authorized to access real-time configs.
`REAL_TIME_CONFIG_INVALID_FOR_SCHEMA`	29002	400	Config values fail JSON Schema validation.
`REAL_TIME_CONFIG_INVALID_SCHEMA`	29004	400	JSON Schema definition is invalid.
`REAL_TIME_CONFIG_UNKNOWN_CLIENT_ENVIRONMENT`	29006	400	Client environment is not one of `sandbox`, `pre-release`, or `live`.

Accounts and projects

Code	ID	HTTP	Description
`ACCOUNT_NOT_FOUND`	1002	404	Account ID does not exist.
`ACCOUNT_CREATE_INVALID_ID`	1004	400	Account ID contains non-alphanumeric characters or is too similar to an existing ID.
`ACCOUNT_CREATE_EXISTING_ID`	1006	409	Account ID is already taken.
`PROJECT_NOT_FOUND`	15001	404	Project ID does not exist.
`PROJECT_ID_ALREADY_EXISTS`	15005	409	Project ID is already taken.
`PROJECT_ID_INVALID`	15006	400	Project ID does not meet format requirements.

SMS

Code	ID	HTTP	Description
`SMS_TEMPLATE_NOT_FOUND`	20001	404	SMS template ID does not exist.

Test suite

Code	ID	HTTP	Description
`MissingTestCasesHttp`	—	422	One or more test case IDs were not found.
`NoTestCasesHttp`	—	422	No test cases exist for this project.

WebSocket close codes

If you are using the WebRTC Gateway or webchat WebSocket connections, you may encounter these close codes:

Code	Meaning	When it occurs
1000	Normal closure	Connection closed cleanly.
1006	Abnormal closure	Connection dropped unexpectedly (for example, network failure).
408	Pong timeout	Server did not receive a pong response within the configured timeout.

Troubleshooting

Every API response includes an X-PolyAI-Correlation-Id header. When contacting PolyAI support, include this value so the team can trace the request through the system.

Common patterns

Quick diagnostics for the errors you are most likely to hit. Expand a row to see the likely cause and how to resolve it.

401 on every request

Likely cause — API key missing or malformed.Resolution — Verify the x-api-key header is present and correctly formatted. Check for stray whitespace or missing characters when the key is copied from a secret store.

403 after key rotation

Likely cause — Old key revoked.Resolution — Confirm you are using the new key everywhere it is referenced — including local .env files, CI secrets, and any deployed services.

404 for a known resource

Likely cause — Wrong region.Resolution — Verify the base URL matches your account region. See API getting started for the list of regional base URLs.

409 on create

Likely cause — Duplicate identifier.Resolution — Use a different name or ID, or check for an existing resource with the same identifier before retrying.

422 on import

Likely cause — Schema mismatch.Resolution — Verify CSV columns match the expected format. Check the error data field for column-level details.

API getting started

Authentication, base URLs, and API versioning.

Conversations API

Retrieve conversation data and transcripts.

​Error response format

​Standard HTTP status codes

​Platform error codes

​WebSocket close codes

​Troubleshooting

​Common patterns

​Related pages

API getting started

Conversations API

Error response format

Standard HTTP status codes

Platform error codes

WebSocket close codes

Troubleshooting

Common patterns

Related pages