Troubleshooting Common Issues

Agent receives 401 UnauthorizedPossible causes:

• Missing API key.
• Incorrect Bearer token format.
• Wrong API key.
• Key was regenerated and the agent still uses the old one.

Fix:

• Confirm the header is Authorization: Bearer sg_your_api_key.
• Regenerate the key in Admin → Agents if needed.
• Update the agent’s secret store or environment variables.

Agent receives 403 ForbiddenPossible causes:

• Agent is paused or inactive.
• Polling or API access is disabled.
• Tenant or feature settings prevent the action.

Fix:

• Check the agent status in Admin → Agents.
• Confirm API access settings.
• Contact an admin if feature limits or license settings are involved.

Decision stays pendingPossible causes:

• Reviewer has not decided yet.
• Agent is polling the wrong thread_id or task_id.
• Webhook was configured but the agent does not poll as fallback.

Fix:

• Open the inbox and confirm the thread is visible.
• Confirm the agent saved the returned thread_id.
• Poll GET /api/agent/decisions using the correct identifier.
• Ask a reviewer to approve or reject the request.

Webhook is not receivedPossible causes:

• Webhook URL is incorrect.
• Receiver is offline.
• Receiver does not return a 2xx response.
• Network or firewall blocks the request.

Fix:

• Verify the webhook URL in Admin → Agents.
• Check receiver logs.
• Check Stacksona Gate webhook logs.
• Use polling as a fallback.

Reviewers do not have enough contextPossible causes:

• Agent did not log task events.
• Summary is too vague.
• Payload does not include useful fields.
• Attachments or evidence are missing.

Fix:

• Log important events before requesting a decision.
• Include a concise but specific summary.
• Include structured payload fields.
• Attach relevant images or evidence when supported.

Rule did not matchPossible causes:

• Payload parameter name does not match the rule.
• Value type is unexpected.
• Rule threshold or pattern is incorrect.
• Tool name does not match the registered tool.

Fix:

• Confirm the agent’s tool_name.
• Confirm payload keys such as amount, email, or reason.
• Review the rule type and threshold.
• Test with a known payload.