Troubleshooting & Common Errors
Even the best-crafted agents can run into issues. This guide helps you identify and resolve common error codes and behavioral issues.
API Error Codes
| Status | Error | Primary Cause | Recommended Action |
|---|---|---|---|
Snippet | Unauthorized | Missing or expired API key. | Check your Snippet |
Snippet | Forbidden | Key lacks specific permissions. | Verify the key has the correct scope (e.g., Read-Only vs. Manager). |
Snippet | Not Found | Invalid endpoint or resource ID. | Double-check the URL and the ID of the agent or knowledge base you are calling. |
Snippet | Rate Limit | Request frequency too high. | Implement exponential backoff or upgrade your plan for higher throughput. |
Snippet | Server Error | Unexpected internal issue. | Review detailed logs in Settings → Logs. If it persists, contact engineering. |
Knowledge Base & Retrieval Issues
1. Vector DB "No matches found"
If your agent isn't retrieving context correctly:
- Index Latency: New documents take 2-5 minutes to be fully indexed.
- Embedding Mismatch: Ensure the embedding model used for upload matches the agent's configuraiton.
- Chunk Size: If documents are too large, try re-uploading with a smaller chunk size (e.g., 500 characters).
2. Slow Response Times
Low latency is critical for conversational UX. If responses are slow:
- Model Choice: GPT-4o is powerful but slower than Gemini 1.5 Flash. Try a lighter model for speed.
- Tool Chaining: Multiple custom tools can add significant latency. Audit your agent's tool-calling logic.
Integration Failures
Webhook Timeouts
Webhooks must respond within 10 seconds. If your endpoint takes longer:
- Accept the webhook immediately with a .Snippet
200 OK - Process the task in the background.
- Use the Crafted API to push the result back to the agent.
Still stuck?
Our engineering team monitors all
Snippet
5xx