Errors and Troubleshooting

HTTP Status Behavior

• 200 for successful GraphQL transport (even when query-level errors may exist)
• 400 for malformed requests
• 403 for forbidden docs path access
• 404 for unsupported or missing routes
• 405 for unsupported HTTP method on docs routes

GraphQL Error Envelope

The server returns GraphQL-style errors in an errors array.

{

  "errors": [

    {

      "message": "Validation failed",

      "extensions": {

        "code": "BAD_USER_INPUT"

      }

    }

  ]

}

Common Issues

Authentication Fails

• Confirm X-Access-Key value is correct.
• If using query parameter fallback, ensure access_key is URL encoded.
• Verify bypass mode is not unexpectedly disabled in your environment.

No Data Returned

• Check siteId against the sites query response.
• Confirm your date range contains event data.
• Remove optional filters to isolate an over-constrained query.

Validation Errors

• Ensure required input fields are present.
• Verify enum values exactly match schema casing.
• Keep DateRangeInput start/end valid and ordered.

Debugging Tip

Enable SQL verification logs in environments where query inspection is allowed:

• CLICKHOUSE_QUERY_LOG_ENABLED=true

This logs generated SQL details at debug level through the app logger.