Errors

Reference Herm API error response bodies, HTTP status codes, validation failures, authentication problems, and common recovery steps.

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. Terminal errors may also include "retryable": false; do not resubmit the same request when that field is present.

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 busy request mixes prompt and control events, or archiving a running session
409	no_active_turn	The session has no live turn for a steer or interrupt control event
410	response_expired	The turn that requested an approval, clarification, or synchronous custom-tool result has ended; do not retry the same response
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.

File already exists

{
  "error": "conflict",
  "message": "Path reports/q3.md already exists"
}

Retry with overwrite: true, or choose a different path.

File or directory not found

{
  "error": "not_found",
  "message": "Path reports/missing.md was not found"
}

List the workspace with the Files API before reading or deleting a path.

Turn already in progress

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

A session runs one turn at a time. Prompt-only requests are queued automatically; this error means the request contains events that cannot be queued together. Send prompt and control events separately — 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" }