Error handling - Cotality developer portal

Error shape

Errors use the same response envelope with success: false. Detail is in the messages array.

{
  "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
`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
`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
`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

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.

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.

Back off on 429 and 5xx

Use exponential backoff with jitter. Cap retries at 3. Log the full messages array for support.

Correct 422 before retrying

Semantic validation failures (bad dates, bad enums) will recur on retry. Read the messages detail to understand the correction needed.

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.

​Error shape

​HTTP status codes

​Common error codes

​Guidance for AI agents

Error shape

HTTP status codes

Common error codes

Guidance for AI agents