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

# Error handling

> How Cotality signals errors — HTTP status codes, the error envelope, common error codes, and what AI agents should do for each class.

## Error shape

Errors use the same [response envelope](/reference/response-envelope) with `success: false`.
Detail is in the `messages` array.

```json theme={null}
{
  "success": false,
  "count": 0,
  "data": [],
  "messages": [
    { "code": "ENTITLEMENT_DENIED", "message": "Asset not licensed for this token." }
  ]
}
```

## HTTP status codes

| HTTP  | Class       | Meaning                                                                          | Agent action                                              |
| ----- | ----------- | -------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `400` | Validation  | Malformed input — bad filter, missing required param, invalid enum value         | Fix the request; do not retry as-is                       |
| `401` | Auth        | Missing or expired bearer token                                                  | Refresh token; retry once                                 |
| `403` | Entitlement | Token valid but asset not licensed                                               | Stop; surface to user — do not loop                       |
| `404` | Not found   | No property, CLIP, or geography matched                                          | Report no match; never fabricate a value                  |
| `422` | Semantic    | Valid shape but invalid values (e.g., date out of range, unsupported product ID) | Correct values per asset limits                           |
| `429` | Rate limit  | Too many requests                                                                | Back off; see [Rate limits](/reference/rate-limits)       |
| `5xx` | Server      | Transient upstream error                                                         | Retry with exponential backoff + jitter; cap at 3 retries |

## Common error codes

| Code                         | Cause                                                               | Fix                                                                                   |
| ---------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `ENTITLEMENT_DENIED`         | Asset or tool not licensed for this token                           | Contact Cotality account team                                                         |
| `CLIP_NOT_FOUND`             | Address did not resolve to a CLIP                                   | Re-check and standardize the address; see [Identifiers](/ontology/identifiers)        |
| `INVALID_GEOGRAPHY`          | `geography_type` / `geography_type_values` pair is invalid          | Use a supported type and valid code format                                            |
| `OUT_OF_RANGE_DATE`          | Requested date is outside the asset's available history or forecast | Adjust to the asset's temporal limits; see [Data freshness](/ontology/data-freshness) |
| `UNSUPPORTED_PRODUCT_ID`     | `product_id` is not a supported value                               | Use a value from the documented enum                                                  |
| `DOWNSTREAM_ENCOMPASS_ERROR` | Encompass origin or transaction lookup failed                       | Verify EPC context; retry once                                                        |
| `ORDER_FAILED`               | EPC order completed in a failed state                               | Check `messages` for EPC-specific reason                                              |
| `VALIDATION_FAILED`          | Business-rule validation failed on the request payload              | Review required fields and conditional rules                                          |

## Guidance for AI agents

<Steps>
  <Step title="Never fabricate on 404">
    If a CLIP, property, or geography does not resolve, tell the user — do not invent a value or assume the closest match.
  </Step>

  <Step title="Do not loop on 403">
    Entitlement errors will not fix themselves by retrying. Stop immediately and surface the error to the user or escalation path.
  </Step>

  <Step title="Back off on 429 and 5xx">
    Use exponential backoff with jitter. Cap retries at 3. Log the full `messages` array for support.
  </Step>

  <Step title="Correct 422 before retrying">
    Semantic validation failures (bad dates, bad enums) will recur on retry. Read the `messages` detail to understand the correction needed.
  </Step>
</Steps>

<Warning>
  Error codes are illustrative of the common classes. The exact codes and messages returned depend on the specific tool or API endpoint. Always log the full `messages` array.
</Warning>