Example
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "The requested role could not be found",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/api-reference/errors-v2/unkey/data/role_not_found"
  }
}

​
What Happened?

This error occurs when you’re trying to perform an operation on a role that doesn’t exist in the Unkey system. Roles in Unkey are collections of permissions that can be assigned to users or API keys. Common scenarios that trigger this error:
  • Using an incorrect role ID or name
  • Referencing a role that has been deleted
  • Trying to assign a role that doesn’t exist in the current workspace
  • Typos in role names when using name-based lookups
Here’s an example of a request that would trigger this error: 
# Attempting to add a permission to a non-existent role
curl -X POST https://api.unkey.com/v1/roles.addPermission \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
  -d '{
    "roleId": "role_nonexistent",
    "permissionId": "perm_123abc"
  }'

​
How To Fix

Verify that you’re using the correct role ID or name and that the role still exists in your workspace:
  1. List all roles in your workspace to find the correct ID
  2. Check if the role has been deleted and recreate it if necessary
  3. Verify you’re working in the correct workspace
Here’s how to list all roles in your workspace: 
curl -X GET https://api.unkey.com/v1/roles.listRoles \
  -H "Authorization: Bearer unkey_YOUR_API_KEY"
If you need to create a new role, use the appropriate API endpoint: 
curl -X POST https://api.unkey.com/v1/roles.createRole \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
  -d '{
    "name": "API Reader",
    "description": "Can read API information"
  }'

​
Common Mistakes

  • Incorrect identifiers: Using wrong role IDs or names
  • Deleted roles: Referencing roles that have been removed
  • Case sensitivity: Role names might be case-sensitive
  • Workspace boundaries: Trying to use roles from another workspace