Error Handling¶

All API errors return a JSON response body with a detail field describing the problem.

Error Response Format¶

{
  "detail": "Description of what went wrong"
}

HTTP Status Codes¶

Status Code	Meaning	Typical Cause
`200 OK`	Success	Request processed and response returned
`422 Unprocessable Entity`	Validation Error	Missing or wrong-type request fields
`500 Internal Server Error`	Server Error	LLM call failed, SQL error, or service misconfiguration

Common Errors¶

422 — Validation Error¶

Returned when a required field is missing or has the wrong type.

POST /api/v1/chat/ask HTTP/1.1
Content-Type: application/json

{}

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "question"],
      "msg": "Field required",
      "input": {},
      "url": "https://errors.pydantic.dev/2.11/v/missing"
    }
  ]
}

500 — OpenAI Quota Exceeded¶

If the OpenAI API rate limit is hit:

{
  "detail": "429 You exceeded your current quota, please check your plan and billing details."
}

Resolution

Check your OpenAI billing dashboard and ensure your API key has an active quota. Consider implementing exponential backoff retries for production.

500 — SQL Execution Error¶

If Vanna generates syntactically invalid SQL:

{
  "detail": "no such column: loan_amount"
}

Resolution

Add more training examples to ChromaDB that demonstrate the correct column names. Re-running vn.train(ddl=...) and vn.train(question=..., sql=...) improves accuracy.