ValueError
azure.core.exceptions.HttpResponseError (ValueError on API version mismatch)
Stack trace
ValueError: The API version '2023-05-15' is not supported by the Azure OpenAI service endpoint. Please use a supported API version.
File "app.py", line 42, in main
client.chat.completions.create(...)
File "azure/ai/openai/_client.py", line 123, in create
raise ValueError("The API version is not supported by the service endpoint.") Why it happens
Azure OpenAI service endpoints require the client to specify an API version that matches the deployed service version. If the client uses an unsupported or incorrect API version string, the service rejects the request with a version mismatch error. This often happens when the SDK or client code is updated without aligning the API version parameter with the Azure resource's supported versions.
Detection
Check for ValueError exceptions during client initialization or API calls indicating unsupported API version. Log the API version string used and compare it against the Azure portal's supported versions for your resource.
Causes & fixes
Client code specifies an API version string not supported by the Azure OpenAI resource.
Update the client configuration to use a supported API version string exactly as documented in the Azure portal or SDK release notes.
Using an outdated Azure SDK version that defaults to an old API version no longer supported by the service.
Upgrade the azure-ai-openai SDK to the latest version which supports current API versions.
Manually overriding the API version parameter with a typo or incorrect format.
Verify the API version string is correctly formatted and matches one of the official supported versions, e.g., '2023-05-15'.
Code: broken vs fixed
from azure.ai.openai import OpenAIClient
import os
client = OpenAIClient(
endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
credential=os.environ["AZURE_OPENAI_KEY"],
api_version="2022-12-01" # Incorrect or unsupported API version
)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}]
) # This line raises ValueError due to API version mismatchfrom azure.ai.openai import OpenAIClient
import os
client = OpenAIClient(
endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
credential=os.environ["AZURE_OPENAI_KEY"],
api_version="2023-05-15" # Fixed to supported API version
)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content) # Works without version errorWorkaround
If you cannot immediately update the API version, catch the ValueError and log the error details, then fallback to a default supported API version or notify the user to update configuration.
Prevention
Always verify and align the API version parameter in your Azure OpenAI client with the supported versions listed in the Azure portal or official SDK documentation before deployment.