Error codes

HTTP status codes and platform-specific error codes returned by PolyAI APIs.

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.

Related pages

API getting started

Authentication, base URLs, and API versioning.

Conversations API

Retrieve conversation data and transcripts.