*REST API › Errors*

# `insufficient_scope`

> HTTP HTTP 403.

HTTP status: `403` · Problem type: `https://docs.filmo.io/errors/insufficient_scope`

## When it happens

403. The key is valid but does not carry the scope the operation requires. The missing scope is named in `requiredScope`. Without an `Accept-Language` header this error uses the preferred language of the key's owner. This is about the key; [`forbidden`](https://docs.filmo.io/rest-api/errors/forbidden) is about the key's owner and [`addon_required`](https://docs.filmo.io/rest-api/errors/addon_required) is about the plan.

## What to do

Create a new key that includes the scope named in `requiredScope`. The scopes of an existing key are fixed.

## Retry

| Condition | What to do | Note |
| --- | --- | --- |
| 401 · 402 · 403 (key, owner or plan) | Stop | Do not retry: resending the same request fails again. Act on the key, its owner or the plan: use a valid key with the right scope, ask an administrator for the missing permission, or add the add-on. |

## Fields of errors[]

| Name | Type | Description |
| --- | --- | --- |
| `requiredScope` | string | On `insufficient_scope`: the scope the API key needs. |

## Example

*insufficient_scope*

```json
{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "orders:write"
}
```

## Returned by

`insufficient_scope` can be returned by any operation.

## Through MCP

A tool call that fails comes back with `isError` set and the problem as structured content, with the same `code`.

---

Canonical URL: https://docs.filmo.io/rest-api/errors/insufficient_scope  
Last updated: 2026-10-25