Errors

Every Operata API endpoint returns standard HTTP status codes and, where useful, a stable string error.code you match on — use that code in your error-handling logic, not the human-readable message.

Endpoint

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

Parameters

This page covers error responses. The error shape applies to every endpoint; check each endpoint’s own reference page for the codes it emits.

Response

Operata returns errors as JSON in a stable envelope:

{
  "error": {
    "status": 400,
    "code": "invalid_range",
    "message": "to must be after from."
  }
}

Field	Type	Description
`error.status`	integer	The HTTP status code, repeated in the body for clients that only parse JSON.
`error.code`	string	A short, stable identifier. Match on this, not on `message`.
`error.message`	string	A human-readable summary. Wording can change between releases; do not parse it.

Example

An error response from a reversed time window on the contact summary endpoint:

curl -i -u "$OPERATA_GROUP_ID:$OPERATA_API_TOKEN" \
  "https://api.operata.io/v1/data/calls?fromTime=2026-05-18T00:00:00Z&toTime=2026-05-17T00:00: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-05-18T00:00:00Z", "toTime": "2026-05-17T00:00:00Z"},
)
if response.status_code >= 400:
    body = response.json().get("error", {})
    print(body["code"], body["message"])

Status	Code	When	Recover
400	`invalid_request`	The request body or query string did not validate against the endpoint schema.	Read `error.message` and fix the client. Do not retry until the input changes.
400	`invalid_range`	`fromTime` and `toTime` are missing, equal, or out of order.	Send a window where `toTime` is strictly after `fromTime`.
400	`invalid_config`	The redaction config body failed validation (returned as `REDACTION_CONFIG not valid` today).	Check the field names against Data redaction and re-send.
401	`unauthorized`	The `Authorization` header is missing, malformed, or the credentials are wrong.	See Authentication. Rotate the token if you suspect it leaked.
403	`forbidden`	The credentials are valid but the Operata account does not have access to the resource.	Ask an account admin to grant the relevant role.
404	`not_found`	The resource you requested does not exist for this Operata account. Examples: an unknown `contactId`, a redaction config that has not been created yet.	Confirm the identifier. For redaction config, create it with `PUT /v1/config/json` first.
409	`conflict`	A write conflicts with current state (for example, deleting a resource that another request just deleted).	Re-fetch the current state and decide whether to retry.
422	`invalid_signal`	A submitted signal payload references fields that the platform does not recognize.	Compare your payload against the relevant glossary page in Data reference, for example Contact trace records.
429	`rate_limited`	You exceeded the per-token request budget.	Back off using the `Retry-After` header. See Rate limits.
500	`internal_error`	An unexpected error in the Operata platform.	Retry with exponential backoff. If it persists, capture the response and contact support.
502	`bad_gateway`	A downstream dependency (Amazon Connect, Kinesis) is unreachable.	Retry with exponential backoff.
503	`service_unavailable`	The platform is in a brief degraded state, typically during a deploy.	Retry with exponential backoff.
504	`gateway_timeout`	An upstream request took longer than the gateway allows.	Retry with exponential backoff. Narrow the query window if it persists.

Overview & quickstart

API essentials

Endpoints — Contacts

Endpoints — Logs

Endpoints — Users

Endpoints — Data redaction

Events & webhooks

Streaming & backends

AI & MCP

Errors

Endpoint

Parameters

Response

Example

Errors

​Endpoint

​Parameters

​Response

​Example

​Errors

Endpoint

Parameters

Response

Example

Errors