Insufficient scope

What it means

The credential is valid but does not hold the scope this operation needs.

Common causes

• The API key was created without that scope.
• The person did not approve that scope when they connected the app.
• The app’s scope ceiling does not include it.

What to do

Find the required scope in the API reference and compare it with GET /v1/meta. Use a key that holds it, or ask the person to reconnect and approve it.

Retry: only after a fix. The same request fails the same way until you change the request, the credential or the resource.

This response also carries WWW-Authenticate, which says how to authenticate and where the sign-in metadata lives.

Over MCP, the same failure is a tool result with isError: true, the code insufficient_scope and retryable: false.

Example

A response body for this problem. The detail and instance vary with the request.

{
  "type": "https://api.tobie.team/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This operation requires the tasks:write scope",
  "code": "insufficient_scope",
  "instance": "/v1/tasks",
  "requestId": "01JC0S7Z5F3X9QK2M4N6P8R0TV"
}