Troubleshooting Common Issues in Agent Therapy API

This guide covers the most common issues you may encounter when using Agent Therapy, along with step-by-step fixes. If you work through the relevant section and your problem is still unresolved, contact our support team at support@agenttherapy.ai with your session ID or request details and we’ll investigate promptly.

Authentication Errors

401 Unauthorized

Your API key is either missing from the request or invalid.What to check:

Confirm you’re passing your key in the Authorization header using the Bearer scheme:
Authorization: Bearer at_live_xxxxxxxxxxxxxxxxxxxx
Verify the key is active in Dashboard → Settings → API Keys. A key that has been rotated or deleted will always return 401.
Make sure there are no leading/trailing spaces in the key value — copy it directly from the dashboard.

Never hardcode your API key in client-side code or commit it to version control. Use environment variables or a secrets manager.

403 Forbidden

Your API key is valid and recognized, but it doesn’t have permission to perform the requested action.What to check:

Plan limits — some endpoints (e.g., bulk export, EU region access) are restricted to Pro or Enterprise plans. Check whether the feature you’re calling is available on your current plan.
Key scopes — if you created a restricted key (e.g., read-only), it won’t be able to create sessions or modify settings. Generate a new key with the correct scopes in Settings → API Keys → Create Key.
Resource ownership — you cannot access sessions or agents that belong to a different organization.

429 Too Many Requests

You’ve exceeded the API rate limit for your key. Limits are applied per minute, per key.What to check:

Inspect the response headers for limit details:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710000060

Implement exponential backoff in your client — wait, then retry with increasing delays:

import time, random

def submit_with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        response = fn()
        if response.status_code != 429:
            return response
        wait = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(wait)
    raise Exception("Max retries exceeded")

If you’re consistently hitting limits, consider batching requests or upgrading your plan for a higher rate ceiling.

Session Issues

Session stuck in 'processing'

Sessions typically complete within 10–30 seconds. If a session has been in processing for more than 5 minutes, something has likely gone wrong.What to do:

Poll the status endpoint to get the current state and check for an error field:

curl https://api.agenttherapy.ai/v1/sessions/{session_id} \
  -H "Authorization: Bearer <your_key>"

{
  "id": "sess_abc123",
  "status": "processing",
  "error": null
}

If error is non-null, follow the guidance in the Session returns failed status section below.
If error is null and it’s been more than 5 minutes, contact support with the session ID — this may indicate a processing node issue on our end.

Session returns 'failed' status

A failed status means Agent Therapy received your log but could not analyze it. The response body will contain details:

{
  "id": "sess_abc123",
  "status": "failed",
  "error": {
    "code": "LOG_TOO_SHORT",
    "message": "Submitted log contains fewer than 3 turns. A minimum of 3 turns is required for analysis."
  }
}

Common error codes and fixes:

`error.code`	Cause	Fix
`MALFORMED_LOG`	Log JSON is invalid or missing required fields	Validate your log against the log schema docs
`EMPTY_LOG`	Log was submitted with no messages	Ensure your export pipeline is capturing messages before submission
`LOG_TOO_SHORT`	Fewer than 3 conversation turns	Submit a longer sample; 3 turns is the minimum for meaningful analysis

Review the log schema requirements in the Sessions API reference to validate your log format before submission. Catching format errors early avoids consuming a session credit.

Low confidence findings

If your session results show findings with confidence: low, the log you submitted may not contain enough signal for the models to produce high-confidence assessments.Why this happens:

Logs with fewer than ~10 turns produce lower confidence scores across most finding categories.
Sparse logs (long gaps between turns, very short messages) provide less behavioral data.

What to do:

Submit a longer conversation sample — aim for at least 20–50 turns for accurate analysis.
For agents with short individual conversations, batch multiple conversations together in a single log submission.

The Conversation Coverage panel in the session detail view shows how much of each behavioral dimension was observable given your log length.

Health score seems too low or too high

The Agent Health Score reflects only the log you submitted, not your agent’s lifetime history or overall behavior.Common reasons a score seems off:

Too low — the submitted log may have captured an unusual or edge-case conversation batch. Try submitting a more representative sample from a typical operational period.
Too high — a short or narrow log might not expose the issues that occur in broader usage. Increase the sample size and diversity of conversations.

If you believe a score is systematically miscalibrated for your agent type or use case, use the Feedback button on the session detail page to flag it — this directly informs model improvement.

Integration Problems

LangChain callback not firing

If you’re using the Agent Therapy LangChain handler and no sessions are being created, the callback is likely not attached at the right level.Most common mistake — attaching to the LLM instead of the agent:

# ❌ Wrong — callback only fires for LLM calls, misses agent-level events
llm = ChatOpenAI(callbacks=[AgentTherapyHandler()])
agent = initialize_agent(tools, llm, ...)

# ✅ Correct — callback fires for all agent events
handler = AgentTherapyHandler(api_key="at_live_xxx")
agent = initialize_agent(tools, llm, callbacks=[handler])

Also check:

Enable verbose=True on the agent temporarily to confirm the callback chain is executing:
agent = initialize_agent(tools, llm, callbacks=[handler], verbose=True)
Ensure the handler is not catching and silently swallowing exceptions — set raise_error=True during debugging.

OpenAI thread export returns empty

If the exported thread contains no messages, check the following:

Thread ID — confirm the thread ID is correct. OpenAI thread IDs follow the format thread_xxxxxxxxxxxxxxxxxx. A typo will return an empty thread rather than an error.

API key scopes — your OpenAI key must have the threads:read scope (also listed as “Thread messages: Read” in the OpenAI platform permissions UI). Keys without this scope return an empty message list silently.

# Verify the thread exists and your key can read it
curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

Thread age — OpenAI automatically deletes threads after 60 days of inactivity. Threads older than this cannot be retrieved.

AutoGen messages missing timestamps

By default, AutoGen’s message objects don’t include timestamps, and some export configurations strip metadata. Agent Therapy will still process and score logs without timestamps — no action is required.However, be aware:

Temporal analysis (e.g., detecting response latency patterns or time-based drift) will be skipped when timestamps are absent.
Overall scoring accuracy may be slightly reduced compared to logs with full metadata.

To add timestamps, wrap AutoGen message capture with your own metadata layer:

from datetime import datetime, timezone

def capture_message(sender, message, recipient):
    return {
        "role": sender.name,
        "content": message,
        "timestamp": datetime.now(timezone.utc).isoformat()
    }

Dashboard & UI Issues

Agent not appearing in dashboard

After registering a new agent via the API, it appears in the dashboard immediately — no waiting period is required.If you don’t see it:

Hard-refresh the page (Cmd+Shift+R on macOS, Ctrl+Shift+R on Windows/Linux) to clear any cached state.
Confirm the registration request returned a 201 Created response with an agent ID. A 200 OK without an agent ID indicates the call may have hit a read endpoint instead.
Check that you’re logged into the correct organization — agents are org-scoped and won’t appear if you’re viewing a different org’s dashboard.

Alerts not firing

If you’ve configured alerts but aren’t receiving notifications, work through the following:For all alert channels:

Go to Settings → Alerts and confirm the alert rule is enabled (toggle is green) and the threshold is set correctly.
Check the Alert History tab to see if the alert fired but the notification failed, or if it never triggered at all.

For Slack webhooks:

Verify the webhook URL is correct — Slack webhook URLs follow the format https://hooks.slack.com/services/T.../B.../....
Confirm the Slack app connected to the webhook still has posting permissions for the target channel. If the channel was made private after the webhook was created, permissions may have been revoked.

Test the webhook directly:

curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL \
  -H "Content-Type: application/json" \
  -d '{"text": "Agent Therapy webhook test"}'

A successful test returns ok. Any other response indicates a permissions or URL issue.

For PagerDuty and Datadog:

Re-authenticate the integration in Settings → Integrations — access tokens can expire.
Confirm the integration key or API key used has write permissions on the target service.

Getting More Help

Contact Support

Reach our support team directly. Include your session ID or request ID for the fastest resolution.

API Status

Check real-time API uptime, ongoing incidents, and historical availability on our status page.

Get Started

Core Concepts

Guides

Integrations

Support

Troubleshooting Common Issues in Agent Therapy API

Authentication Errors

Session Issues

Integration Problems

Dashboard & UI Issues

Getting More Help

Contact Support

API Status

​Authentication Errors

​Session Issues

​Integration Problems

​Dashboard & UI Issues

​Getting More Help

Contact Support

API Status

Authentication Errors

Session Issues

Integration Problems

Dashboard & UI Issues

Getting More Help