> ## Documentation Index
> Fetch the complete documentation index at: https://docs.operata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every HTTP status code and stable `error.code` the Operata API returns, with the recovery pattern for each.

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

```http theme={null}
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:

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash curl theme={null}
  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"
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

## Errors

| 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](/docs/api-data-redaction) and re-send.                                                            |
| 401    | `unauthorized`        | The `Authorization` header is missing, malformed, or the credentials are wrong.                                                                         | See [Authentication](/docs/api-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](/docs/contact-trace-records). |
| 429    | `rate_limited`        | You exceeded the per-token request budget.                                                                                                              | Back off using the `Retry-After` header. See [Rate limits](/docs/api-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.                                                                          |