Troubleshooting

Common issues

"Action blocked" or "Denied"

Your policy is denying the action. Check the policy rules—the first matching rule wins. Add a rule that allows the action, or adjust the match conditions. The action response includes reason and optionally reason_code (e.g. DEFAULT_DENY_NO_MATCH, POLICY_DENY): use them to see why (no rule matched vs. a rule explicitly denied). Add or adjust a policy rule and try again.

"Which rule matched?"

The reason and reason_code in the action response indicate which outcome applied. Order matters: the first matching rule wins. Use the dashboard or GET /v1/actions/{id} to inspect the action; use faramesh policy validate and test with a sample action if needed.

"Pending approval" but no notification

Make sure Slack or email is configured in Settings > Notifications. Org admins set this up. Until then, approve from the dashboard under Approvals.

API key not working

• Check you're using the right key (copy it again from the dashboard if needed)

• Ensure the Authorization: Bearer <key> header is set correctly

• Revoke and create a new key if you think it was compromised

"402 Payment Required" or "Credits exhausted"

Your org is out of credits for the billing period. Upgrade your plan from Billing, or wait for the period to reset.

Agent not showing in the dashboard

Agents appear after they've submitted at least one action. Use Connect Agent to register one manually before its first action.

Policy changes not taking effect

Activate the policy after editing. Only the active policy is used. If self-hosting, restart the server or enable policy hot-reload.

Server unreachable / timeout

If the Faramesh server is down or slow, the SDK or integration may time out. Check the server with GET /health or GET /ready. Integrations (e.g. OpenClaw) default to fail-closed: when the server is unreachable, tool calls are blocked. For self-hosted, check logs and network; for Horizon, check status or contact support.

Canonicalization or hash errors

Errors about canonicalization, invalid JSON, or non-finite numbers (NaN/Infinity) mean the action payload failed validation. Ensure params and context are valid JSON objects; avoid NaN/Infinity. The server returns 400 and does not execute (fail-closed).

"409 Conflict" or invalid state

Approval and result endpoints return 409 when the action is not in the right status (e.g. approving when not pending_approval, or posting a result when not executing). Check the action with GET /v1/actions/{id} and follow the lifecycle.

Rate limits (Horizon)

If you see 429 Too Many Requests, back off and retry. For sustained load, consider upgrading or batching requests.

Getting help

Check the docs for your use case (policies, API, Core Spec). For Horizon, contact support through your dashboard or the Faramesh website.