JuliusBrussee/caveman · error

azure Foundry api-version %q is not supported

Error message

azure Foundry api-version %q is not supported

What it means

For Azure Foundry v1 inference routes, the only accepted api-version values are 'v1' and 'preview' (these are GA labels of the Models API, not dated versions). If exactly one api-version is present and it is neither — e.g. a dated legacy version like 2024-10-21 — the request is rejected before upstream resolution. The GA v1 surface intentionally does not accept legacy dated versions.

Source

Thrown at proxy/providers/azureopenai/azure_routing.go:45

}

// ResolveUpstreamURL validates either the legacy deployment route or the
// current Foundry Models v1 inference route before resolving upstream.
func (a Adapter) ResolveUpstreamURL(ctx context.Context, req *http.Request, route providers.RouteContext) (*url.URL, error) {
	if err := validateAzureRequest(req.URL); err != nil {
		return nil, err
	}
	return a.Base.ResolveUpstreamURL(ctx, req, route)
}

func validateAzureRequest(u *url.URL) error {
	if foundryV1InferenceRoute(u.Path) {
		versions := u.Query()["api-version"]
		if len(versions) > 1 {
			return fmt.Errorf("azure request has duplicate api-version values")
		}
		if len(versions) == 1 && versions[0] != "v1" && versions[0] != "preview" {
			return fmt.Errorf("azure Foundry api-version %q is not supported", versions[0])
		}
		return nil
	}
	if !legacyChatCompletionsRoute(u.Path) {
		return fmt.Errorf("azure legacy inference path %q is not supported", u.Path)
	}
	versions := u.Query()["api-version"]
	if len(versions) > 1 {
		return fmt.Errorf("azure request has duplicate api-version values")
	}
	version := ""
	if len(versions) == 1 {
		version = versions[0]
	}
	if version == "" {
		return fmt.Errorf("azure request missing api-version")
	}
	if !apiVersionAllowed(version) {

View on GitHub (pinned to 27d5a3981a)

Solutions

  1. On /openai/v1/... routes send api-version=v1 (or 'preview'), or omit it entirely.
  2. If you need a dated version, use the legacy route /azure/openai/deployments/<deployment>/chat/completions?api-version=<date> instead.
  3. Update the client SDK config so it stops injecting its default dated version.

Example fix

# before
curl "$PROXY/azure/openai/v1/chat/completions?api-version=2024-10-21"

# after
curl "$PROXY/azure/openai/v1/chat/completions?api-version=v1"
Defensive patterns

Strategy: validation

Validate before calling

const foundryPath = "/openai/v1/chat/completions" // or /openai/v1/responses
v := u.Query().Get("api-version")
if strings.HasPrefix(strings.TrimPrefix(u.Path, "/azure"), "/openai/v1/") {
    if v != "" && v != "v1" && v != "preview" {
        return fmt.Errorf("Foundry v1 routes accept only api-version=v1|preview, got %q", v)
    }
}

Type guard

func foundryVersionOK(v string) bool {
    return v == "" || v == "v1" || v == "preview"
}

Try / catch

if err := validateAzureRequest(req.URL); err != nil {
    if strings.Contains(err.Error(), "Foundry api-version") {
        http.Error(w, "use api-version=v1 or preview on /openai/v1/ routes (dated versions belong to the legacy deployments route)", http.StatusBadRequest)
        return
    }
    http.Error(w, err.Error(), http.StatusBadRequest)
}

Prevention

When it happens

Trigger: Calling /azure/openai/v1/chat/completions?api-version=2024-10-21 — mixing the legacy deployment-style dated version with the new v1 route; SDK defaults tuned for the old API reused on the Foundry route.

Common situations: Migrating a client from the legacy deployments/... route to the v1 route while keeping the old api-version; SDK configuration that always stamps a dated version; docs/examples written for the legacy surface.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/fbf7d3cb2ec2aa3f. Report an issue: GitHub.