roboflow/supervision · error · ValueError

Azure API returned an error {azure_result['error']['message'

Error message

Azure API returned an error {azure_result['error']['message']}

What it means

Detections.from_azure_analyze_image parses the JSON body returned by the Azure AI Vision Image Analysis 4.0 API. Azure reports failures inside the 200-response body as an 'error' object rather than an HTTP error status, so supervision checks for that key and re-raises the message as a ValueError.

Source

Thrown at src/supervision/detection/core.py:1022

            endpoint = "https://.cognitiveservices.azure.com/"
            subscription_key = ""

            headers = {
                "Content-Type": "application/octet-stream",
                "Ocp-Apim-Subscription-Key": subscription_key
             }

            response = requests.post(endpoint,
                headers=self.headers,
                data=image
             ).json()

            detections = sv.Detections.from_azure_analyze_image(response)
            ```
        """
        if "error" in azure_result:
            raise ValueError(
                f"Azure API returned an error {azure_result['error']['message']}"
            )

        xyxy, confidences, class_ids = [], [], []

        is_dynamic_mapping = class_map is None
        if class_map is None:
            class_map = {}

        inverted_map: dict[str, int] = {value: key for key, value in class_map.items()}

        for detection in azure_result["objectsResult"]["values"]:
            bbox = detection["boundingBox"]

            tags = detection["tags"]

            x0 = bbox["x"]
            y0 = bbox["y"]

View on GitHub (pinned to 7f254d9784)

Solutions

1. Inspect azure_result['error'] fully (code + message) — it states the real cause (auth, quota, bad request).
2. Verify the subscription key and endpoint: key must match the endpoint's region, and the endpoint must be the Image Analysis .../computervision/imageanalysis:analyze URL.
3. If quota/billing is the cause, enable the tier that covers the 'objects' feature or wait for the rate window to reset.
4. Only pass responses where the call succeeded; check 'error' in response before feeding into from_azure_analyze_image.

Example fix

# before
response = requests.post(endpoint, headers=headers, data=image).json()
detections = sv.Detections.from_azure_analyze_image(response)  # crashes on error body

# after
response = requests.post(endpoint, headers=headers, data=image)
response.raise_for_status()
result = response.json()
if 'error' in result:
    raise RuntimeError(f"Azure API failed: {result['error']['message']}")
detections = sv.Detections.from_azure_analyze_image(result)

def is_azure_success(result: dict) -> bool:
    return isinstance(result, dict) and 'error' not in result and 'objectsResult' in result

if not is_azure_success(response_json):
    raise RuntimeError(f"Azure failed: {response_json.get('error', 'missing objectsResult')}")
detections = sv.Detections.from_azure_analyze_image(response_json)

try:
    detections = sv.Detections.from_azure_analyze_image(result)
except ValueError as e:
    if 'Azure API returned an error' in str(e):
        logger.error('azure vision failed: %s', result.get('error'))
        detections = sv.Detections.empty()  # explicit policy, not silent fallback
    else:
        raise

When it happens

Trigger: Calling from_azure_analyze_image(azure_result) where the dict contains an 'error' key — typically because the requests.post to the endpoint returned an auth failure, quota exhaustion, wrong endpoint URL, or invalid request payload, and .json() of that response was passed through.

Common situations: Wrong or expired Ocp-Apim-Subscription-Key; using a free-tier key against a feature not enabled; wrong endpoint region; forgetting that the response must come from the analyze endpoint with 'objects' output; Azure returning 401/429 bodies.

Related errors

• Downloaded asset {filename} failed MD5 verification.
• Data pointed by URL could not be decoded into image.

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/31594ce901b9c5e5. Report an issue: GitHub.