Limits

Hexel Studio applies three kinds of limits:

• Rate limits cap how many requests a caller and an organization can make per minute.
• Plan limits cap how many workspaces, environments, members and invitations an organization can have.
• Credential lifetimes decide how long API keys and tokens stay valid.

Rate limits

Rate limits apply to the identity and access API: every route under https://api.hexelstudio.com/v1/ for organizations, members and invitations, workspaces, environments, users, policies, groups, roles, service users and their credentials, access checks, audit logs and quotas.

Requests are counted per calendar minute, for the caller (the user, service user or role session in the token) and for the caller's organization. A request must fit within every limit that applies to it:

A sensitive write counts against both the writes limit and the sensitive writes limit. A request sent with an API key counts for the key's service user.

If your organization needs higher read or write limits, contact Hexel Studio. The sensitive writes limit is the same for everyone.

Token service limits

Reuse an access token for its 15 minutes instead of requesting one per call, and the token limit won't affect you.

When you hit a rate limit

The API answers 429 Too Many Requests:

{
  "error": {
    "code": "429",
    "message": "Rate limit exceeded. Try again later."
  }
}

The token service answers 429 with a body of its own:

{
  "error": "rate_limited",
  "error_description": "too many tokens issued for this credential; retry later"
}

Wait for Retry-After seconds before you retry. Retrying sooner is refused again and still counts.

Plan limits

Some creates count against a limit of your organization's plan. These are the defaults:

Your organization's limits can differ from the defaults. Read your organization's limits to see the values that apply to you.

A few consequences of the defaults:

• A new organization already has one workspace, Default, so you can create two more.
• The Default workspace starts with two environments, Production and Development, so it's already at the default environment limit.
• A pending invitation holds a member slot until it's accepted, revoked or expires. Accepting it doesn't use a second slot.

A limit applies only to new creates. If your organization is already above a limit, you keep what you have.

When you hit a plan limit

The create is refused with 403, even when the caller is allowed to make it:

{
  "error": "quota_exceeded",
  "quota_key": "workspaces_per_org",
  "limit": 3,
  "current": 3,
  "message": "plan limit reached: this organization can have at most 3 workspaces; upgrade the plan or contact Hexel"
}

To create more, delete something you no longer need, or contact Hexel Studio.

Read your organization's limits

Any access token or API key of your organization can read its effective limit for a key. No policy is needed.

curl https://api.hexelstudio.com/v1/quotas/orgs/$ORG_ID/limits/workspaces_per_org \
  -H "X-API-Key: $API_KEY"

{
  "org_id": "org_7b2e4c1a9d8f4e3b8c6a5d4e3f2a1b0c",
  "quota_key": "workspaces_per_org",
  "limit": 3,
  "source": "default"
}

$ORG_ID must be your own organization: the one in your token or API key. Another organization's ID answers 403, and an unknown key answers 404 with "error": "unknown_quota_key".

Credential and token lifetimes

See Access tokens for how tokens are renewed and revoked, and Service users and API keys for rotating keys before they expire.