Errors

API errors return a JSON body with an error code and a human-readable message. Treat the HTTP status and error as the machine-readable contract.

Error format

{
  "error": "error_code",
  "message": "Human-readable description of what went wrong"
}

Error codes

HTTP Status	Error Code	Description
400	`validation_error`	The request body or parameters are invalid
401	`unauthorized`	The API key is missing, invalid, or revoked
403	`forbidden`	The authenticated caller cannot perform the operation
404	`not_found`	The requested resource does not exist in the authenticated organization
409	`conflict`	An optimistic concurrency check failed
409	`invalid_state`	The session state does not allow the operation — e.g. a prompt-starting `user.message` while a turn is running, or archiving a running session
409	`no_active_turn`	The session is no longer waiting for the submitted control or tool-result event
429	`rate_limited`	Too many requests — back off and retry
500	`server_error`	An unexpected error occurred on the server
502	`server_error`	An upstream credential or connector operation failed; retry only when the operation is safe to repeat
502	`hermes_delete_failed`	Herm could not delete the session from the runtime; retry the session deletion
503	`server_error`	A required service is temporarily unavailable; retry with exponential backoff

Interpret server_error together with its HTTP status. A 500 is an unexpected internal failure, a 502 identifies an upstream operation failure, and a 503 is explicitly temporary and retryable.

Validation errors

400 validation_error messages name the failing field path and the violated constraint, one path: constraint entry per issue, separated by ;. The offending value is never echoed back.

{
  "error": "validation_error",
  "message": "events[0].content[0].text: Expected a string at most 20000 character(s) long"
}

Common scenarios

Missing API key

curl "https://api.herm.run/v1/agents"

Returns 401 unauthorized with Invalid or missing API key.

Agent version conflict

{
  "error": "conflict",
  "message": "Agent changed from version 2 to 3"
}

Fetch the agent again and retry the full update body with the latest expectedVersion.

Turn already in progress

{
  "error": "invalid_state",
  "message": "A turn is already in progress"
}

A session runs one turn at a time. Either wait for the running turn to end, or send the message with delivery: "when_idle" so Herm queues it and starts it automatically once the session is idle — see Queue a message while a turn is running.

Rate limits

Per-agent user limits return a structured 429 response:

{
  "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

resource is conversations or messages. Wait at least the integer number of seconds in Retry-After before retrying. Handle rate_limited explicitly in your client. Successful operations include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. See Rate limits for configuration and counting behavior.

Agent not found

{ "error": "not_found", "message": "Agent not found" }

Getting Started

Agents

Sessions and events

Capabilities

Credentials

Resources

Error format

Error codes

Validation errors

Common scenarios

Missing API key

Agent version conflict

Turn already in progress

Rate limits

Agent not found

​Error format

​Error codes

​Validation errors

​Common scenarios

​Missing API key

​Agent version conflict

​Turn already in progress

​Rate limits

​Agent not found

Error format

Error codes

Validation errors

Common scenarios

Missing API key

Agent version conflict

Turn already in progress

Rate limits

Agent not found