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.

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.

Status	Meaning	When it occurs
400	Bad request	The request body or query parameters failed validation.
401	Unauthorized	Missing, expired, or invalid API key or token.
403	Forbidden	You do not have permission for the requested action.
404	Not found	The requested resource does not exist.
405	Method not allowed	The HTTP method is not supported for this endpoint.
408	Request timeout	The request exceeded the server timeout.
409	Conflict	A resource with the same identifier already exists.
410	Gone	The resource has been permanently deleted.
412	Precondition failed	A required precondition was not met (for example, deploying to live before pre-release).
415	Unsupported media type	The uploaded file type is not supported.
422	Unprocessable entity	The request is well-formed but contains semantic errors.
429	Too many requests	Rate limit exceeded. Retry after the period indicated in the response headers.
500	Internal server error	An unexpected error occurred on the server.
501	Not implemented	The requested functionality is not yet available.
502	Bad gateway	An upstream service returned an error or timed out.
503	Service unavailable	The service is temporarily unavailable.

Platform error codes

PolyAI APIs return domain-specific error codes alongside HTTP status codes. There are 63 of them across 13 categories — search by code, ID, or keyword below, or filter by HTTP status, instead of scanning tables.

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

Include the correlation ID in support requests

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

Symptom	Likely cause	Resolution
401 on every request	API key missing or malformed	Verify the x-api-key header is present and correctly formatted.
403 after key rotation	Old key revoked	Confirm you are using the new key.
404 for a known resource	Wrong region	Verify the base URL matches your account region.
409 on create	Duplicate identifier	Use a different name or ID, or check for existing resources.
422 on import	Schema mismatch	Verify CSV columns match the expected format. Check the error data field for column details.

Related pages

API getting started

Authentication, base URLs, and API versioning.

Conversations API

Retrieve conversation data and transcripts.