INSUFFICIENT_SCOPE — Key missing required scope

Summary

Your key authenticates, but it doesn’t have a scope this endpoint requires. The most common case: a read-only key trying to call a write endpoint like POST /v1/code.

HTTP status

403 Forbidden. Standard envelope.

Example response

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint requires the 'write' scope. Your key has: ['read'].",
    "request_id": "req_01HXJZK4ABCDEF",
    "doc_url": "https://docs.surveycoder.io/errors/insufficient-scope"
  }
}

Why this happens

• The key was created with read-only scope and is being used for writes.
• The endpoint requires the import scope (used by bulk import endpoints) and the key only has read + write.
• An admin reduced a key’s scopes after it was already in use.

How to fix it

1. Check the required scope in the API reference — every endpoint lists its scope under Security.
2. Open surveycoder.io/api-keys and either:
   • Generate a new key with the right scopes, or
   • Edit the existing key to add the missing scope.
3. For least-privilege setups, use separate keys per scope rather than one mega-key. A leaked read-only key is much safer than a leaked write key.

Related

• UNAUTHORIZED
• AUTH_ERROR