Troubleshooting

“Connection refused”

Your agent cannot reach the TapPass server.

Symptoms

ConnectionError: Connection refused — https://tappass.example.com

or

tappass.errors.TapPassConnectionError: Failed to connect to TapPass

Causes and fixes

Cause	Fix
TapPass server is not running	Check with your platform team. Run curl https://tappass.example.com/health to verify.
Wrong URL	Verify the URL in your Agent(url=...) constructor or OPENAI_BASE_URL env var.
Network / firewall	Ensure your agent can reach the server. Check VPN, firewall rules, and DNS resolution.
TLS certificate	If using self-signed certs, set TAPPASS_TLS_VERIFY=false (development only).

Quick diagnostic

# Check if TapPass is reachable
curl -s https://tappass.example.com/health | python -m json.tool

# Check if your API key works
curl -s -H "Authorization: Bearer tp_abc123..." \
  https://tappass.example.com/v1/models

SDK resilience

If you need your agent to continue operating when TapPass is temporarily unavailable, configure a resilience policy:

from tappass import Agent
from tappass.resilience import ResiliencePolicy, FailMode

agent = Agent(
    "https://tappass.example.com",
    "tp_abc123...",
    resilience=ResiliencePolicy(mode=FailMode.FAIL_OPEN_CACHED),
)

See SDK Resilience for details.

---

”Policy blocked my request”

A governance pipeline step blocked your request.

Symptoms

tappass.PolicyBlockError: Request blocked by detect_pii — PII detected in prompt

or in the HTTP response:

{
  "error": {
    "message": "Request blocked by policy",
    "type": "policy_block",
    "blocked_by": "detect_pii",
    "reason": "PII detected: EMAIL, PHONE_NUMBER"
  }
}

How to read the block reason

Every block includes:

• blocked_by — which pipeline step blocked the request (e.g. detect_pii, detect_secrets, rate_limit)
• reason — human-readable explanation
• classification — data classification that triggered the block (e.g. CONFIDENTIAL)

Common blocks and fixes

Step	Block reason	Fix
detect_pii	PII in prompt or response	Use flags={"pii": "mask"} to redact instead of block. Or remove PII from your prompt.
detect_secrets	API key / password in prompt	Remove secrets from prompt text. Use tool calls to access secrets.
detect_injection	Prompt injection detected	Review your prompt for injection patterns. If it is a false positive, your platform team can adjust the threshold.
rate_limit	Too many requests	Wait and retry. See Rate limited below.
budget_enforcement	Token budget exceeded	Contact your platform team to increase the budget.
content_safety	Unsafe content	Review the content. Content safety blocks cannot be overridden by flags.
filter_tools	Tool not allowed	The agent’s policy does not permit this tool. Contact your platform team.

Adjusting policy (platform team)

Platform teams can adjust step behavior through policy configuration:

{
  "steps": {
    "detect_pii": {
      "on_detection": "redact"
    }
  }
}

The on_detection action can be: block, redact, notify (log and continue), or allow.

Using governance mode flags

Set the governance mode to control overall strictness:

# Observe mode — log everything, block nothing
agent = Agent("https://tappass.example.com", "tp_...", flags={"mode": "observe"})

# Warn mode — flag detections, do not block
agent = Agent("https://tappass.example.com", "tp_...", flags={"mode": "warn"})

See Governance Flags for the full reference.

---

”Token expired”

A capability token has exceeded its time-to-live (TTL).

Symptoms

Authorization failed: Token expired at 1711500000

How TTL works

Capability tokens have a configurable TTL. The default is 5 minutes. When a token expires, the agent must request a new one from the control plane.

Setting	Default	Description
Default TTL	5 minutes	For standard execution tokens
Maximum TTL	90 days	Hard cap enforced by the SDK
PoP window	30 seconds	Proof-of-Possession signature validity

Fixes

Cause	Fix
Token too short-lived	Increase TTL when minting the token (talk to your platform team)
Clock skew	Ensure your agent’s system clock is synced (NTP). PoP allows a 30-second window in each direction.
Token not refreshed	Implement token refresh logic — request a new token before the old one expires

SDK cache behavior

The SDK caches responses for resilience purposes (not for performance). Cache TTL defaults to 300 seconds (5 minutes) and is separate from token TTL.

Setting	Default	Env var
Cache TTL	300s	TAPPASS_CACHE_TTL
Max cached entries	50	—

The cache is keyed by (model, last_user_message). It only serves cached responses when TapPass is unreachable and the resilience mode is fail_open_cached.

---

”Pipeline timeout”

The governance pipeline took too long to process your request.

Symptoms

Pipeline timeout after 120s

Timeout configuration

Setting	Default	Description
Per-step timeout	30 seconds	Maximum time for any single step
Total pipeline timeout	120 seconds	Maximum time for all steps combined
Request timeout (SDK)	30 seconds	Client-side timeout (configurable)

Which steps are slow?

Most steps run in under 10 milliseconds. Steps that can be slow:

Step	Why it is slow	Fix
call_llm	Waiting for the LLM provider	Not a pipeline issue — the provider is slow. Try a faster model.
inspect_images	Image analysis for multimodal requests	Disable if you do not send images: "inspect_images": {"enabled": false}
external_detection	Calling an external detection API	Check network latency to the external service
detect_injection	ML-based injection detection on long prompts	Increase threshold or switch to rule-based mode
content_safety	Content moderation on long prompts	Increase threshold or skip for trusted agents

Disabling expensive steps

Platform teams can disable steps in the pipeline configuration:

{
  "steps": {
    "inspect_images": { "enabled": false },
    "external_detection": { "enabled": false }
  }
}

Or use governance flags to reduce overhead:

# Observe mode skips blocking actions (still logs)
agent = Agent("https://tappass.example.com", "tp_...", flags={"mode": "observe"})

---

“Rate limited”

Too many requests in the configured time window.

Symptoms

{
  "error": {
    "message": "Rate limit exceeded: 105/100 calls in 3600s",
    "type": "policy_block",
    "blocked_by": "rate_limit"
  }
}

or for token budgets:

{
  "error": {
    "message": "Token rate limit exceeded: 1,050,000/1,000,000 tokens in 3600s"
  }
}

Rate limit configuration

Rate limits are configured per-organization in the pipeline policy:

{
  "steps": {
    "rate_limit": {
      "max_calls": 100,
      "window_seconds": 3600,
      "max_tokens": 1000000
    }
  }
}

Per-agent vs per-org limits

Scope	How it works
Per-agent	Each agent has its own counter. Agent A hitting its limit does not affect Agent B.
Per-org	All agents in the organization share a pool. One agent can exhaust the limit for all.
Per-user	Rate limits scoped to the end-user making the request through the agent.

The scope is determined by how the rate limit key is configured. By default, limits are per-agent.

What to do

1. Wait. Rate limits use a sliding window. Once the oldest requests fall outside the window, new requests are allowed.
2. Check your usage. Use the audit trail to see how many requests your agent is making.
3. Request a higher limit. Contact your platform team to increase the cap.
4. Optimize your agent. Reduce unnecessary LLM calls — cache results client-side, batch requests, use cheaper models for simple tasks.