# INSUFFICIENT_SCOPE

The API key lacks the required permissions (scopes) for this operation.

<Callout type="info">
**Category:** [Authentication](/errors/category/auth)
</Callout>

| | |
|---|---|
| HTTP status | `403` Forbidden |
| Retry | After fixing the cause |

## When it happens

The API key is valid but lacks a permission (scope) the operation needs. It can happen on any operation, and it is checked before the body and the parameters, so it comes first even when they are also wrong. `error.details.required_scopes` lists what the operation requires and `error.details.missing_scopes` what the key lacks.

## How to fix it

Create a key that includes the missing scopes, or add them to the key, then retry. The reference page of each operation lists its required scopes.

## Retry

Not as is: the same request fails the same way. Fix the cause described above, then send the request again, under a new `Idempotency-Key` if the body changed.

## Example response

When this error occurs, the API answers `403` Forbidden with a JSON body of this shape:

```json
{
  "type": "https://docs.beel.es/errors/INSUFFICIENT_SCOPE",
  "title": "INSUFFICIENT_SCOPE",
  "detail": "The API key lacks the required permissions (scopes) for this operation.",
  "instance": "/v1/<resource>",
  "errors": [],
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key lacks the required permissions (scopes) for this operation.",
    "details": {}
  },
  "meta": {
    "timestamp": "2026-05-21T10:00:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
```

The `type` URI is stable and always resolves to this page.

## Message

<Tabs items={["English", "Spanish", "Catalan"]}>
  <Tab value="English">{"The API key lacks the required permissions (scopes) for this operation."}</Tab>
  <Tab value="Spanish">{"La API key no tiene los permisos (scopes) necesarios para esta operación."}</Tab>
  <Tab value="Catalan">{"L'API key no té els permisos (scopes) necessaris per a aquesta operació."}</Tab>
</Tabs>

Send the request with `Accept-Language: <es|en|ca>` to receive the message in your preferred language.

## Other errors in this category

<div className="grid grid-cols-2 gap-3 not-prose">
  <Card title="ACCOUNT_MANAGEMENT_FORBIDDEN" description="Only the owner or an admin can manage account settings." href="/errors/ACCOUNT_MANAGEMENT_FORBIDDEN" />
  <Card title="ACCOUNT_NOT_ACCESSIBLE" description="You do not have access to that account" href="/errors/ACCOUNT_NOT_ACCESSIBLE" />
  <Card title="ACCOUNT_REQUIRES_FOCUS_SWITCH" description="You are a member of that account, but it is not your active account right now. Switch your active account and try again." href="/errors/ACCOUNT_REQUIRES_FOCUS_SWITCH" />
  <Card title="ACTIVE_COMPANY_HEADER_INVALID" description="Header '‹value›' must contain a company identifier (UUID)." href="/errors/ACTIVE_COMPANY_HEADER_INVALID" />
  <Card title="ACTIVE_COMPANY_NOT_ACCESSIBLE" description="The selected company does not belong to your account" href="/errors/ACTIVE_COMPANY_NOT_ACCESSIBLE" />
</div>

## Keep exploring

<div className="grid grid-cols-2 gap-3 not-prose">
  <Card title="All Authentication errors" description="Every code in this category in one table." href="/errors/category/auth" />
  <Card title="Error reference home" description="Browse every category or jump to the handling guide." href="/errors" />
</div>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi