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 | |:-------|:------|:--------------|:-------------------| | 401 | Unauthorized | Missing or expired API key. | Check your x-api-key header and ensure your key is active in the Dashboard. | | 403 | Forbidden | Key lacks specific permissions. | Verify the key has the correct scope (e.g., Read-Only vs. Manager). | | 404 | Not Found | Invalid endpoint or resource ID. | Double-check the URL and the ID of the agent or knowledge base you are calling. | | 429 | Rate Limit | Request frequency too high. | Implement exponential backoff or upgrade your plan for higher throughput. | | 500 | 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 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 5xx errors in real-time. For specific implementation hurdles, reach out via the Support Portal.