Common issues

Fixes for the problems people hit most often.

My agent is not receiving messages

• Check that the Target URL in your gateway is correct and publicly reachable.
• Check Insights → Logs for DELIVERY_FAILED entries. If present, your endpoint is down or returning errors.
• If the gateway is paused, messages bypass filters but still get delivered — check your endpoint directly.

I'm getting 401 Unauthorized

• Your message source is sending the wrong secret. Verify the X-Gateway-Secret header matches the one shown at creation.
• For WhatsApp: make sure the Verify Token in Meta matches your gateway secret.

Too many messages are being blocked

• Check which filter is causing it in Insights → Flow (the health markers show you).
• If it's rate limiting, increase the max messages or widen the window.
• If it's dedup, your source may be sending retries — shorten the dedup window.
• If it's token budget, increase the limit or check if your source sends unexpectedly large payloads.

Messages arrive but without the _portarus envelope

• The envelope is appended to the JSON body as a top-level key. Make sure your agent parses the full body, not just specific fields.
• If meta.passthrough: "paused", the gateway is paused — the envelope is minimal.

I hit quota and now messages are bypassing filters

This is by design — at 100% quota, messages are delivered directly to protect continuity. Upgrade your plan or wait for the next billing cycle. You should have received a warning at 90%. See Fail-open design.