docs(endpoints): Add documentation for HogQL variable validation

contents/docs/endpoints/troubleshooting.mdx

@@ -35,6 +35,20 @@ If you get `"Version X not found for endpoint"`:
 - SQL endpoints only accept variables explicitly defined in the query
 - Insight endpoints accept the breakdown property name and `date_from`/`date_to` (non-materialized only)
 
+**"Query references undefined variable(s): X, Y"**
+- Your query uses `{variables.X}` placeholder(s) that don't have matching variable definitions
+- Define the variable in the [data management variables page](https://app.posthog.com/data-management/variables) with a `code_name` matching the placeholder name
+- Ensure the variable is linked to your endpoint
+
+**"Variable ID(s) not valid UUIDs"**
+- Variable IDs must be valid UUID format
+- Check that you're using the correct variable ID from [data management variables](https://app.posthog.com/data-management/variables)
+
+**"Variable ID(s) not found"**
+- The variable ID(s) don't exist in your project
+- Create the variable in [data management variables](https://app.posthog.com/data-management/variables)
+- Verify you're using the correct project
+
 > **Note:** `filters_override` is deprecated and will be removed in a future release. Use `variables` instead. See the [variables documentation](/docs/endpoints/variables) for migration guidance.
 
 ## Rate limiting (429)

contents/docs/endpoints/variables.mdx

@@ -36,6 +36,20 @@ curl -X POST \
   "<ph_app_host>/api/projects/{project_id}/endpoints/{endpoint_name}/run"
 ```
 
+### Variable validation
+
+When you create or update an endpoint, PostHog validates that every variable placeholder in your query has a matching variable definition.
+
+For each `{variables.X}` placeholder in your query, you must define a variable with `code_name` set to `X`. Create and manage variables in [data management variables](https://app.posthog.com/data-management/variables).
+
+If validation fails, you'll see one of these errors:
+
+- **"Query references undefined variable(s)"** - Your query uses a placeholder that doesn't have a matching variable definition. Define the variable with the correct `code_name`.
+- **"Variable ID(s) not valid UUIDs"** - Variable IDs must be valid UUIDs.
+- **"Variable ID(s) not found"** - The variable doesn't exist. Create it in data management first.
+
+See [troubleshooting](/docs/endpoints/troubleshooting#variable-errors) for more details.
+
 ### Materialization
 
 SQL-based endpoints with variables can be [materialized](/docs/endpoints/materialization) when each variable is used in a `WHERE` clause with a supported comparison operator.