> ## Documentation Index
> Fetch the complete documentation index at: https://unkey-eng-3082-add-portal-config-crud-api-endpoints-v2portal.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# custom_domain_limit_exceeded

> The workspace already holds as many custom domains as its plan allows, so no further domain can be attached.

<Danger>`err:unkey:limits:custom_domain_limit_exceeded`</Danger>

```json Example theme={"theme":"kanagawa-wave"}
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "Your plan does not allow another custom domain. Upgrade your plan, or remove a domain you no longer need, then retry.",
    "status": 403,
    "title": "Forbidden",
    "type": "https://unkey.com/docs/errors/unkey/limits/custom_domain_limit_exceeded"
  }
}
```

## What Happened?

You called `createDomain` for a workspace that has already attached every custom domain its plan permits.

The allowance is counted per workspace, across every project, app, and environment in it. Attaching domains to different environments does not raise it, so a workspace allowed one domain cannot hold one per environment.

## How To Fix

1. Check how many domains the workspace already holds, and whether any are still in use.
2. Remove one you no longer need, from the app's settings page in the dashboard.
3. If they are all still in use, upgrade the plan to raise the allowance.
4. Retry the request.

```bash theme={"theme":"kanagawa-wave"}
# Attach the domain once the allowance has room
curl -X POST https://api.unkey.com/v2/domains.createDomain \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
  -d '{
        "project": "payments",
        "app": "payments-api",
        "environment": "production",
        "domain": "api.acme.com"
      }'
```

## Common Mistakes

* **Expecting the allowance to be per environment**: A domain in each environment still counts against one workspace-wide allowance.
* **Counting only verified domains**: A domain still `pending` verification occupies the allowance, so an abandoned setup keeps taking a slot.
* **Retrying on a schedule**: Nothing about the workspace changes between attempts, so a retry loop fails until the plan or the domain list changes.

## Related Errors

* [err:unkey:data:domain\_already\_exists](../data/domain_already_exists) - When the name is already attached to this workspace
* [err:unkey:authorization:forbidden](../authorization/forbidden) - When the root key or its workspace is disabled