# Insufficient Scope

Source: https://apiguide.dev/errors/insufficient-scope
Problem type URI: https://apiguide.dev/errors/insufficient-scope
Status: 403 Forbidden
Updated: 2026-10-14

## When to use it

Use 403 with an Insufficient Scope error when the client's credentials (like an API token or OAuth access token) are valid and authenticated, but the token lacks the specific permissions or scopes needed to access the requested resource or perform the HTTP action.

A common example is a token generated with a `read` scope attempting to perform a `POST`, `PUT`, or `DELETE` request.

## When not to use it

Do not use this if the client is unauthenticated (use `unauthorized` or 401). Do not use this if the token is expired (use `expired-authentication-token` / 401). If the token's scopes are sufficient but your own permission rules deny the action, such as a non-owner deleting a project, use `forbidden`.

## Example response

```json
{
  "type": "https://apiguide.dev/errors/insufficient-scope",
  "title": "Insufficient Scope",
  "status": 403,
  "detail": "The token provided lacks the required 'leads:write' scope.",
  "instance": "/v1/leads"
}
```

Include a `WWW-Authenticate` header naming the missing scope, per RFC 6750:

```http
WWW-Authenticate: Bearer error="insufficient_scope", error_description="The request requires the 'leads:write' scope", scope="leads:write"
```