Errors

The Operata API signals errors with the HTTP status code. Error bodies are short plain-text messages, not JSON, so branch on the status code and log the body for context.

Endpoint

Any endpoint under https://api.operata.io

Parameters

This page covers every error the contact data endpoints return, under /v1/data and /v2/data, plus the authentication errors every endpoint shares. For the data redaction and user endpoints, see each endpoint’s page.

Response

Error responses from the data endpoints have a text/plain body. Authentication failures are different: the gateway returns 401 with an HTML error page.

HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

query parameter "toTime" must be after "fromTime"

Message wording can change between releases. Don’t parse it to decide what to do; use the status code.

Example

A request with a reversed time window:

curl -i -u "$OPERATA_GROUP_ID:$OPERATA_API_TOKEN" \
  "https://api.operata.io/v1/data/calls?fromTime=2026-10-13T18:30:00Z&toTime=2026-10-11T18:30:00Z"

import os, requests

response = requests.get(
    "https://api.operata.io/v1/data/calls",
    auth=(os.environ["OPERATA_GROUP_ID"], os.environ["OPERATA_API_TOKEN"]),
    params={"fromTime": "2026-10-13T18:30:00Z", "toTime": "2026-10-11T18:30:00Z"},
)
if response.status_code >= 400:
    print(response.status_code, response.text)

Status	Body	When	Recover
400	Names the parameter, for example `query parameter "toTime" must be after "fromTime"`	A contact summary query parameter is unknown, malformed, repeated, out of range, or missing its pair.	Fix the parameter the message names. Don’t retry unchanged.
400	`Invalid search criteria`	CCP logs `criteria` is missing or isn’t valid JSON.	Send a URL-encoded JSON object.
400	`This GroupId no longer exists.`	The Operata Group your credentials belong to has been deleted.	Contact your Operata administrator.
401	An HTML `401 Authorization Required` page	Credentials are missing, malformed, or wrong.	See Authentication.
404	`Call Summary record could not be found`	No contact summary exists for the contact ID.	Check the ID with List contact summaries.
404	`no matching records found`	No per-second data exists for the contact ID.	Check the ID with List contact summaries.
422	`An error occurred while making ES query`	Contact summary `criteria` isn’t valid JSON.	Fix the JSON and URL-encode it.
422	`An error occurred while retrieving call stats log` or `An error occurred while retrieving agent CCP logs`	OpenSearch rejected or failed the query, for example when paging past its result window.	Fix the query. Retry later if it persists.
422	`Invalid opensearch url`	The data service can’t reach your region’s data store.	Contact support.
500	An HTML error page from the gateway	The authentication layer couldn’t validate your token.	Retry with exponential backoff.
500	Varies	Stored data couldn’t be read or parsed, for example per-second files for detailed contact stats.	Retry with exponential backoff. Contact support if it persists.

Other 5xx statuses come from the infrastructure in front of the API. Retry them with exponential backoff.

Start here

API essentials

Endpoints — Contact data

Endpoints — Admin

Endpoints — Data redaction

Events and webhooks

Releases

Errors

Endpoint

Parameters

Response

Example

Errors

​Endpoint

​Parameters

​Response

​Example

​Errors

Endpoint

Parameters

Response

Example

Errors