*API REST › Errores*

# `insufficient_scope`

> HTTP HTTP 403.

Estado HTTP: `403` · Tipo del problema: `https://docs.filmo.io/errors/insufficient_scope`

## Cuándo ocurre

403. La clave es válida pero no lleva el scope que exige la operación. El scope que falta se nombra en `requiredScope`. Sin la cabecera `Accept-Language`, este error usa el idioma preferido del propietario de la clave. Esto trata de la clave; [`forbidden`](https://docs.filmo.io/es/rest-api/errors/forbidden) trata del propietario de la clave y [`addon_required`](https://docs.filmo.io/es/rest-api/errors/addon_required), del plan.

## Qué hacer

Crea una clave nueva que incluya el scope indicado en `requiredScope`. Los scopes de una clave existente son fijos.

## Reintento

| Condición | Qué hacer | Nota |
| --- | --- | --- |
| 401 · 402 · 403 (clave, propietario o plan) | Parar | No reintentes: reenviar la misma petición vuelve a fallar. Actúa sobre la clave, su propietario o el plan: usa una clave válida con el permiso adecuado, pide a un administrador el permiso que falta o contrata el add-on. |

## Campos de errors[]

| Nombre | Tipo | Descripción |
| --- | --- | --- |
| `requiredScope` | string | En `insufficient_scope`: el permiso (scope) que necesita la clave de API. |

## Ejemplo

*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"
}
```

## Lo devuelven

`insufficient_scope` los puede devolver cualquier operación.

## Por MCP

Una llamada a una herramienta que falla vuelve con `isError` y el problema como contenido estructurado, con el mismo `code`.

---

URL canónica: https://docs.filmo.io/es/rest-api/errors/insufficient_scope  
Última actualización: 2026-10-25