Copy page

Error codes

insufficient_scope

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. See 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.

Text
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).

Text
GET /v1/calls
Authorization: Bearer rai_test_KEY_WITH_CALLS_READ

See all codes in the error-code reference.