# insufficient_scope

- HTTP status: 403
- Retry: No
- Execution: not started
- Admin needed: yes

**Insufficient scope.** Each operation requires specific scopes (listed as `x-required-scopes` in the reference). The key was created without at least one of them.

## What it means

The API returns HTTP 403 with `error.code` set to `insufficient_scope`. The default message is: "This API key does not have the scope this operation requires."

## Common causes

- The key was created with read-only scopes and the operation writes.
- The key lacks an artifact scope such as `transcripts:read`.

## How to identify it

Check the response status (`403`) and `error.code` (`insufficient_scope`). Branch on `error.code`, not on the message text: messages can be reworded, codes do not change within v1. Log `error.request_id` (also sent as the `X-Request-Id` header) so support can find the request.

## How to fix it

- Ask a workspace admin to create a key that includes the scopes in `details.required_scopes`.

## Retry guidance

Sending the request unchanged fails the same way. Fix the cause first (see How to fix it), then send it again.

## Did anything happen?

This request was refused before any call was placed and before anything was charged.

## Idempotency

Nothing was done and nothing was stored (under an Idempotency-Key, if you sent one), so the request can be sent again, with the same key if you used one, once the cause is fixed.

## Who can fix it

A workspace administrator usually has to act, in the RelationsAI console.

## When to contact support

If the error persists after the steps above, contact [support@relationsai.com](mailto:support@relationsai.com). See [Support](/resources/support) for what to include (the `request_id`, the time in UTC, the operation, and whether you used a test or live key) and what never to send (API keys, Authorization headers, webhook signing secrets, recording links, transcripts or customer data).

## Example error response

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the scope this operation requires.",
    "details": {
      "required_scopes": [
        "calls:write"
      ]
    },
    "request_id": "req_oa7zjyztfj7b5q6yacxt67bz",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/insufficient_scope"
  }
}
```

## Incorrect and corrected request

Incorrect: The key was created with `agents:read` only; listing calls needs `calls:read`.

```http
GET /v1/calls
Authorization: Bearer rai_test_KEY_WITH_AGENTS_READ_ONLY
```

Corrected: A key a workspace admin created with `calls:read` (see `details.required_scopes`).

```http
GET /v1/calls
Authorization: Bearer rai_test_KEY_WITH_CALLS_READ
```

See all codes in the [error-code reference](/fundamentals/error-codes).