Check that all three env vars are set in the server environment, that sendHeartbeat() runs at startup, and that the app's own logs show no [ACP] Heartbeat failed line. The client swallows the error deliberately, so the log is the only signal.
A 401 means the key is wrong, revoked, or expired; mint a new one. A 404 on the prompt route means the agent ID in your agentState map does not exist in ACP. The IDs must match exactly.
The webhook is not reaching or not passing verification. Confirm the app's base URL is publicly reachable, that /api/acp/webhook is mounted, and that both sides share the same ACP_WEBHOOK_SECRET. A 403 in your logs points at signature, timestamp drift, or a replayed nonce.
A prompt push is approval-gated, so an unapproved change never leaves ACP. After approval, call fetchPrompt() before the model request. A fetch has a five-second timeout and a 60-second cache. If no cached prompt is available, the SDK returns an empty string; your application must use its own fallback. Record the cached prompt version explicitly when you need version attribution.
Ready to connect an app?
Create the app, paste the integration, watch the first heartbeat arrive.