identity_already_exists

{  "meta": {    "requestId": "req_2c9a0jf23l4k567"  },  "error": {    "detail": "An identity with this external ID already exists",    "status": 409,    "title": "Conflict",    "type": "https://unkey.com/docs/errors/unkey/data/identity_already_exists"  }}

What Happened?#

This error occurs when you're trying to create an identity with an external ID that already exists in your Unkey workspace. External IDs must be unique within a workspace to avoid confusion and maintain data integrity.

Common scenarios that trigger this error:

• Creating an identity with an external ID that's already in use
• Re-creating a previously deleted identity with the same external ID
• Migration or import processes that don't check for existing identities
• Duplicate API calls due to retries or network issues

Here's an example of a request that would trigger this error:

# Attempting to create an identity with an external ID that already existscurl -X POST https://api.unkey.com/v2/identities.createIdentity \  -H "Content-Type: application/json" \  -H "Authorization: Bearer unkey_YOUR_API_KEY" \  -d '{    "externalId": "user_123",    "meta": {      "name": "John Doe",      "email": "john@acme.com"    }  }'

How To Fix#

When you encounter this error, you have several options:

1. Use a different external ID: If creating a new identity, use a unique external ID
2. Update the existing identity: If you want to modify an existing identity, use the update endpoint instead
3. Get the existing identity: If you just need the identity information, retrieve it rather than creating it
4. Implement upsert logic: Use a get-or-create pattern in your code

Here's how to update an existing identity:

curl -X POST https://api.unkey.com/v2/identities.updateIdentity \  -H "Content-Type: application/json" \  -H "Authorization: Bearer unkey_YOUR_API_KEY" \  -d '{    "externalId": "user_123",    "meta": {      "name": "John Doe",      "email": "updated_email@acme.com"    }  }'

Or implement a get-or-create pattern in your code:

// Pseudocode for get-or-create patternasync function getOrCreateIdentity(externalId, meta) {  try {    // Try to create the identity    return await createIdentity(externalId, meta);  } catch (error) {    // If it already exists (409 error), get it instead    if (error.status === 409) {      return await getIdentity(externalId);    }    // Otherwise, rethrow the error    throw error;  }}

Common Mistakes#

• Not checking for existing identities: Failing to check if an identity already exists before creating it
• Retry loops: Repeatedly trying to create the same identity after a failure
• Case sensitivity: Not accounting for case sensitivity in external IDs
• Cross-environment duplication: Using the same external IDs across development and production environments

Related Errors#

• err:unkey:data:identity_not_found - When the requested identity doesn't exist
• err:unkey:authorization:insufficient_permissions - When you don't have permission to perform operations on identities