Error codes
A reference for the stable error codes Harriet returns, mostly from the LLM proxy. Desktop apps can show these messages verbatim, so this is what your people will paste into a support thread.
The error envelope
LLM proxy billing and access errors use one JSON shape:
{"error":{"type":"…","code":"…","message":"…","harriet_action":"…"}}code is stable and safe to match on; message is the human-readable text; harriet_action hints where the app should send the user (for example open_provisioner_console, open_billing_or_add_byok, add_payment_method, open_billing).
Code reference
| Code | Where you see it | What it means | What to do |
|---|---|---|---|
device_llm_access_denied |
Desktop app, HTTP 402 from the LLM proxy | The device called Harriet's LLM gateway but is not allowed to use it — typically it is configured for Claude Desktop with Claude account only. Message: "This device is not allowed to use Harriet LLM access. Update the device to "Claude Desktop (no Claude account)" in the Harriet console." | On the device detail page, enable the right surface under Allowed desktop providers. See Model availability. |
insufficient_credits |
Desktop app, HTTP 402 from the LLM proxy | The organization's prepaid managed-credit balance is exhausted, and auto top-up (if enabled) could not refill it. Message: "Your Harriet managed LLM credits have run out. Ask an account admin to top up credits in Harriet → Endpoint AI → Billing, or add your own API key (BYOK) in Provisioner settings." BYOK traffic is unaffected. | An admin tops up in Billing → Credits, or adds a BYOK key for the provider. |
payment_method_required |
Desktop app, HTTP 402 from the LLM proxy | Balance is empty and automatic top-up is enabled, but no saved card exists. Message: "Automatic top-up is enabled but no saved payment method is on file. An account owner should add a card under Harriet billing, or disable auto top-up and purchase credits manually." | An account owner adds a payment method, or the org buys a credit pack manually. See Credits. |
monthly_auto_topup_cap_reached |
Desktop app, HTTP 402 from the LLM proxy | Balance is empty and this month's automatic top-ups have already hit the configured cap. Message: "This month's automatic top-up limit has been reached. Ask an admin to raise the monthly cap in Endpoint AI → Billing or purchase credits manually." | An admin raises the monthly cap in Billing or purchases credits manually. |
mcp_audit_upgrade_required |
Provisioner console, HTTP 403 on the Audit log (and when enabling tool debug retention) | The plan does not include tool-level MCP audit. The console shows "Tool-level MCP audit requires Endpoint AI Team or higher." | Upgrade the plan to view audit rows. See Plans and Audit log. |
Agent HTTP statuses without a code
The background agent's own requests can fail with bare HTTP statuses, visible in the agent log on the machine:
| Status | What it usually means | What to do |
|---|---|---|
401 Unauthorized |
The API key stored on the device no longer matches the server — the key was rotated, or the device was deleted and recreated. Also returned by the LLM proxy for an invalid or revoked token, a blocked device, or a provider with no BYOK and no managed key. | Remove the local config and re-enroll with a fresh enrollment token. See Device not syncing. |
403 Forbidden |
The device id in the URL does not match the device that authenticated (for example, config copied from another machine), or the organization's provisioner feature was disabled. | Re-enroll the machine with its own token; if the whole org is affected, check the plan and feature status. |
⚠️
Other auth failures on the LLM proxy stay plain 401 without the envelope. Only billing and device-access blocks use 402 with a coded body.