Skip to main content

​
What it means

The caller authenticated fine, but the workspace’s plan does not include the entitlement this tool requires. details.upgrade_url points to where the user should upgrade. The LLM should not retry — no amount of waiting unlocks a paid feature.

​
How to fix

  • Surface details.upgrade_url to the user; do not silently drop the request.
  • After the user upgrades, retry the original call — no re-auth needed.
  • If you’re an integrator building an app on Aeris, check the workspace plan before offering the tool in your UI.

​
Response envelope

{
  "ok": false,
  "error_envelope": {
    "code": "ENTITLEMENT_LOCKED",
    "message": "This tool requires an upgraded plan.",
    "docs_url": "https://tryaeris.ai/docs/mcp/errors/entitlement-locked",
    "retryable": false,
    "retry_after_ms": null,
    "details": {
      "required_plan": "pro",
      "entitlement_key": "mcp.read_audiences",
      "upgrade_url": "https://tryaeris.ai/settings/billing"
    }
  }
}
Legacy alias subscription_required may still appear in older responses through 2026-Q3. Treat it as an alias for ENTITLEMENT_LOCKED.