1 Reply
What a 500 means
HTTP 500 – Internal Server Error is a generic status code that simply tells you the Voiceflow server could not complete the request. Unlike a 4xx error (which points to something wrong on the client side such as auth, missing project, bad path, etc.), a 500 happens when the server hits an un-handled exception while trying to fulfil a request.
Typical causes when calling the Knowledge-Base Query endpoint
• Malformed JSON – e.g. missing a closing brace, using single quotes, or sending an array where a string is expected.
• Missing required field(s) – the body must contain at least
3. Start with the minimal valid payload to confirm the endpoint works: 4. Add optional fields (chunkLimit, synthesis, settings, tags, filters…) incrementally to find what triggers the error. 5. Retry after a short pause; transient 500s can occur while the KB is publishing. If the minimal request still returns 500, regenerate your API key and confirm the project/K-B you’re targeting is the one that key belongs to. Documentation: https://docs.voiceflow.com (see Knowledge-Base → Query API reference)
question.
• Wrong header – Content-Type must be application/json and the Authorization header must hold a valid Dialog Manager API Key.
• Using an unsupported model name, or an out-of-range value for temperature, chunkLimit, etc.
• Request body that greatly exceeds the size limits (very large question or system strings).
• Issuing the call while the KB is still indexing or immediately after replacing documents.
Quick checklist
1. Ensure you’re POSTing to the correct URL:https://general-runtime.voiceflow.com/knowledge-base/query
2. Headers3. Start with the minimal valid payload to confirm the endpoint works: 4. Add optional fields (chunkLimit, synthesis, settings, tags, filters…) incrementally to find what triggers the error. 5. Retry after a short pause; transient 500s can occur while the KB is publishing. If the minimal request still returns 500, regenerate your API key and confirm the project/K-B you’re targeting is the one that key belongs to. Documentation: https://docs.voiceflow.com (see Knowledge-Base → Query API reference)