Troubleshooting

Common issues across all three surfaces and how to resolve them.

REST: 401 Unauthorized

The X-API-Key header is missing, malformed, expired, or wrong.

• The key must start with ag_ and be sent in the X-API-Key header.
• Create or rotate a key in Dashboard → API Keys.
• If you get "API key expired", the key passed its expiry — mint a new one.

curl https://api.agoralia.app/api/v1/agents \
  -H "X-API-Key: ag_your_key_here"

REST: 403 Missing scope

The key is valid but doesn't have the scope the endpoint requires (e.g. Missing scope: agents:write). Edit the key in Dashboard → API Keys and grant the needed scope, or create a new key with the right scopes.

A 403 can also mean "... is on the do-not-call list" — the destination number is on your DNC list and the call was blocked. Remove it from DNC only if you have a lawful basis.

REST: 422 Unprocessable Entity

The request was authenticated but the platform couldn't act on it. Two common causes:

• "Agent not synced with Vapi — update it first" — the agent was never published. See "Agent not synced" below.
• "Cannot publish an inactive agent" / "Agent could not be published — check its configuration" — fix the agent's config (e.g. set a voice), then publish again.

A 400 instead usually means a malformed field — for example "Invalid phone number" when to_number is not E.164 (it must look like +39...).

Agent not synced → publish it

A freshly created agent has no provider id and cannot place calls until it's published. The fix is always the same: publish the agent.

curl -X POST https://api.agoralia.app/api/v1/agents/<AGENT_ID>/publish \
  -H "X-API-Key: ag_your_key_here"

publish_agent(agent_id="<AGENT_ID>")

agoralia call POST /agents/<AGENT_ID>/publish

429 Too Many Requests (rate limit)

The API is available on every plan, but each workspace has per-plan rate limits (per minute and per day). When you exceed one you get 429 with a message like "API rate limit exceeded (per minute). Slow down and retry shortly." or "API daily rate limit exceeded."

• Slow down and retry after a short back-off.
• Batch or space out requests in loops.
• If you consistently hit the daily limit, upgrade your plan for higher limits.

Recording forbidden in a country

Some jurisdictions legally forbid call recording. The platform enforces this per destination country: even if an agent defaults to recording on, a call to a forbidden country is placed with no audio recorded and no recording_url — the transcript, summary, and structured data still work.

You cannot force recording on where a jurisdiction forbids it. The call response includes a recording advisory explaining what was applied. If you want to disable recording yourself, set recording_enabled: false on the agent or on the individual call.

MCP: OAuth / connection issues

MCP uses OAuth 2.1 with Dynamic Client Registration. If the connection fails:

• Re-add the server and complete the OAuth approval prompt:

  claude mcp add --transport http agoralia https://api.agoralia.app/mcp

• Approve all requested scopes — missing scopes cause tools to fail with permission errors.
• Make sure the transport is http and the URL is exactly https://api.agoralia.app/mcp.

See MCP.

CLI: not authenticated

If agoralia commands fail with an auth error, you haven't logged in (or the token is stale).

1. Mint a CLI token in Dashboard → API Keys → "CLI token".
2. Log in (the default URL is production):

   agoralia auth login --token <TOKEN>

If the agoralia command itself isn't found, install the CLI from the repo with pip install agoralia-cli. See CLI.

Still stuck?

• Re-check Authentication for your surface.
• Confirm your wallet has credit — calls draw from a prepaid balance.
• Review the API endpoints reference for exact request shapes.