Skip to main content

​
What it means

Aeris uses fine-grained OAuth scopes. Most mutating tools require an apply scope on top of the default read scope. If a caller with a read-only grant invokes a mutating tool, the request fails with SCOPE_INSUFFICIENT. The user must re-consent to add the missing scope — refreshing the token alone will not help.

​
How to fix

  • Compare details.required with details.granted to see which scopes are missing.
  • Redirect the user through the OAuth consent flow again with the extended scope set.
  • Store the refreshed grant; the same tool call should then succeed.

​
Response envelope

{
  "ok": false,
  "error_envelope": {
    "code": "SCOPE_INSUFFICIENT",
    "message": "The current grant is missing a required scope.",
    "docs_url": "https://tryaeris.ai/docs/mcp/errors/scope-insufficient",
    "retryable": false,
    "retry_after_ms": null,
    "details": {
      "required": ["read", "apply"],
      "granted": ["read"]
    }
  }
}