Troubleshooting

Most issues reduce to a policy decision, stale recipient mapping, or beta access state. Check the log entry before changing code — it includes the exact policy rule.

Issue	Fix
Payment is blocked	Check the log entry first. It includes the exact policy rule: service, recipient, amount, budget, approval threshold, or pause state.
service_not_approved	Approve the service id and confirm the registered recipient address. Address changes are treated as new recipients.
budget_exceeded	Lower the payment amount, raise the daily/weekly cap, or wait for the rolling window to clear.
agent_paused	Resume the agent from dashboard or API after confirming the requested service and policy revision.
policy_signer_unavailable	Payments fail closed when AllowKit cannot co-sign. Retry with the same idempotency key.
Webhook retries	Return any 2xx response after persisting the event id. Non-2xx responses are retried with exponential backoff for up to 24h.

See Exact failure modes for the full error-code reference.