Moving Hermes Off a Rate-Limited Free Model After Upgrading

Symptoms

• The Hermes gateway was running and Telegram was connected.
• Telegram messages did not receive useful replies.
• One or more agents remained active in long retry waits.

Evidence

Gateway health was normal:

hermes gateway status
jq '{gateway_state,active_agents,platforms,updated_at}' \
  ~/.hermes/gateway_state.json
stat -c '%y %n' ~/.hermes/state/gateway.heartbeat

Recent service logs showed the actual failure:

journalctl --user -u hermes-gateway.service \
  --since '-10 minutes' --no-pager -o short-iso \
  | grep -Ei '429|rate.limit|capacity'

The configured model was:

model:
  default: stepfun/step-3.7-flash:free
  provider: nous

The provider returned HTTP 429 fair-share errors with a long retry_after period. This was explicitly a model-capacity/fair-share limit, not an invalid API key and not a Telegram connectivity problem.

Root cause

Upgrading the Nous Portal subscription did not automatically replace the configured :free model. The free model retained its independent fair-share limit even though the account had paid model access.

Recovery

Confirm Nous authentication:

hermes portal info
hermes auth status nous

Refresh the live model catalog and open the model picker:

hermes model --refresh --no-browser

Select Nous Portal, then choose the paid model name without the :free suffix:

stepfun/step-3.7-flash

If a normal restart waits for rate-limited turns to drain:

hermes gateway restart --all

--all terminates active gateway work across profiles. Use it only after confirming the active turns are abandoned or stuck and can safely be interrupted.

Verification

Confirm the saved model:

sed -n '1,5p' ~/.hermes/config.yaml

Confirm the gateway is healthy:

hermes gateway status

Run a minimal live inference request:

timeout 90 hermes \
  -z 'Reply with exactly: SUBSCRIPTION_OK' \
  --model stepfun/step-3.7-flash \
  --provider nous

The successful test returned:

SUBSCRIPTION_OK

Prevention

• After changing subscription tiers, refresh the model picker and verify that the configured model matches the intended paid or free variant.
• Diagnose Telegram silence in layers: gateway process, platform connection, heartbeat, then inference-provider logs.
• Do not restart repeatedly for HTTP 429 errors. Restarting does not remove upstream quotas; switch models or wait for the provider’s retry period.