> ## Documentation Index
> Fetch the complete documentation index at: https://docs.herm.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Configure and handle per-subject conversation and message limits for Herm agents.

Each agent has configurable conversation and message limits. Limits are scoped
to the authenticated organization, agent, and stable `subjectId`, so one
customer cannot consume another customer's allowance.

| Resource        | Counted operation               | Default        | Allowed range      |
| --------------- | ------------------------------- | -------------- | ------------------ |
| `conversations` | Successfully create a session   | 5 per minute   | 1-300 per minute   |
| `messages`      | Accept an inbound session event | 100 per minute | 1-1,000 per minute |

Both resources use 60-second windows. A request containing multiple session
events consumes one message point per event.

These per-subject limits are separate from the organization API key's request
ceiling. Newly created organization keys allow up to 1,000 authenticated API
requests per minute across all endpoints. Existing keys retain the limit stored
when they were created.

## Configure limits when creating an agent

Set `rateLimits` in `POST /v1/agents`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.herm.run/v1/agents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "name": "Support agent",
    "modelName": "anthropic/claude-sonnet-4.5",
    "systemPrompt": "Help customers resolve support questions.",
    "skills": [],
    "tools": [],
    "rateLimits": {
      "conversationsPerMinute": 10,
      "messagesPerMinute": 200
    }
  }'
```

Both fields are optional. Omitted fields use their defaults.

## Update limits

```
PATCH /v1/agents/{agentId}/rate-limits
```

Rate limits are mutable operational policy. Updating them does not create a new
agent version and applies to existing sessions.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH "https://api.herm.run/v1/agents/agent_123/rate-limits" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "messagesPerMinute": 250
  }'
```

At least one field is required. An omitted field keeps its current value. The
response is the full updated agent object.

## Subject identity

`subjectId` is your stable identifier for the person, team, organization, or
workspace using an agent. Reuse the same value for the same subject across
sessions. Do not generate a new `subjectId` to bypass limits.

The same `subjectId` can have separate allowances on different agents. Subjects
in different Herm organizations are also isolated.

## Response headers

Rate-limited operations include these headers after checking an allowance:

| Header                | Description                                     |
| --------------------- | ----------------------------------------------- |
| `RateLimit-Limit`     | Maximum points in the current 60-second window. |
| `RateLimit-Remaining` | Points remaining after this request.            |
| `RateLimit-Reset`     | Whole seconds until the allowance resets.       |

A rejected request also includes `Retry-After` with the number of seconds to
wait before retrying.

## Rate-limit errors

When an allowance is exhausted, the API returns `429 rate_limited`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "rate_limited",
  "message": "Message limit reached.",
  "rateLimit": {
    "resource": "messages",
    "limit": 100,
    "remaining": 0,
    "periodSeconds": 60,
    "resetAfterSeconds": 17
  }
}
```

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 429 Too Many Requests
Retry-After: 17
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 17
```

Wait at least the number of seconds in `Retry-After` before retrying. Events
rejected by the message limit are not persisted, queued, or executed. A session
rejected by the conversation limit is not created.

If the allowance cannot be verified, the API returns a retryable
`503 server_error`.