Rate limits

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:

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.

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:

{
  "error": "rate_limited",
  "message": "Message limit reached.",
  "rateLimit": {
    "resource": "messages",
    "limit": 100,
    "remaining": 0,
    "periodSeconds": 60,
    "resetAfterSeconds": 17
  }
}

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.

Getting Started

Agents

Sessions and events

Capabilities

Credentials

Resources

Rate limits

Configure limits when creating an agent

Update limits

Subject identity

Response headers

Rate-limit errors

​Configure limits when creating an agent

​Update limits

​Subject identity

​Response headers

​Rate-limit errors

Configure limits when creating an agent

Update limits

Subject identity

Response headers

Rate-limit errors