INSUFFICIENT

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


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:

{
  "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"
  }
}