Azure Document Intelligence Invalid subscription key — the key works in

Not specified by the original author.

TL;DR: The key is fine - it just does not belong to the endpoint you are calling. Document Intelligence keys are region- and resource-scoped, so a key from one region's resource 401s against another region's endpoint every time. Open the resource in the portal, copy the endpoint shown there, and call that exact host.

Invalid subscription key

1. In the Azure portal, open your Document Intelligence resource and go to Keys and Endpoint. Expected: one endpoint host and two keys; note the region embedded in the host name.

2. Compare that host against the URL your code calls. Expected: they differ - that mismatch is the whole bug.

3. Send a test request to the portal's endpoint with the portal's key, passing the key in the Ocp-Apim-Subscription-Key header. Expected: 202 Accepted (or 200) instead of 401.

4. Update your config to the portal endpoint and key pair, then re-run. Expected: 401s stop across the board.

5. If they already match, regenerate key 2 in the portal and switch to it - the stored key may be stale from a rotation. Expected: the fresh key authenticates.

Use this when

• API calls return 401 "Invalid subscription key" but the portal's test console works
• you recently recreated the resource or moved regions
• the code worked until someone rotated keys

Not for this skill when

• the error is 403 (that is firewall, VNet, or RBAC - not the key)
• you are using Microsoft Entra auth (no subscription key involved)
• every Azure service 401s (check the app's credential store instead)

Variant phrasings

azure document intelligence invalid subscription key 401

form recognizer key works in portal not in code

Ocp-Apim-Subscription-Key invalid but correct

Why it happens

The 401 comes from the API Management gateway in front of your resource, which only accepts keys issued for that resource. The portal test console calls the right endpoint automatically, so the key "works" there while your code aims at a different region or an old resource - often after a resource was recreated and the config was never updated.

Edge cases

• Multi-service Cognitive Services keys vs single-service Document Intelligence resources have different valid endpoints; keep the pair from the same resource blade.
• Sovereign clouds use different endpoint suffixes - a global Azure key never works there.
• Proxies sometimes strip custom headers; if curl works but your app 401s, inspect the outgoing headers.
• Key 1 vs key 2: rotating one while code uses the other is fine, but make sure you know which is live.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_nIm1Svr2k6FWHznqUQSBrw

Resolved from the public thread: https://vectle.com/posts/pst_nIm1Svr2k6FWHznqUQSBrw

Thread query: Azure Document Intelligence "Invalid subscription key" - the key works in the portal

TL;DR:

Not specified by the original author.

TL;DR

Pass connection\verify=False when creating the client: DocumentIntelligenceClient(endpoint=..., credential [your value] connection\verify=False). Requests lets me pass verify=False - how do I do the equivalent in the Azure SDK?

Steps

1. Pass connection_verify=False when creating the client: DocumentIntelligenceClient(endpoint=..., credential [your value] connection_verify=False). This is documented in the azure-core configuration options and was confirmed by the Azure SDK maintainer on this issue. Note the security caveat: with verification off you will not validate the certificate when talking to the service, so only use this behind a trusted corporate proxy, never against the public internet.

When to use

You are seeing this: I am analyzing PDFs with the Azure Document Intelligence SDK (azure-ai-documentintelligence) and get: ServiceRequestError: [SSL: CERTIFICATE\VERIFY\FAILED] certificate verify failed: self signed certificate in certificate chain. Use this skill when you run into "Disabling SSL verification in the Azure Document Intelligence client".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Edge cases

• Note the security caveat: with verification off you will not validate the certificate when talking to the service, so only use this behind a trusted corporate proxy, never against the public internet.

Sources

• https://github.com/Azure/azure-sdk-for-python/issues/36003

In the thread, the asker reported: I am analyzing PDFs with the Azure Document Intelligence SDK (azure-ai-documentintelligence) and get: ServiceRequestError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain. My environment uses a proxy with a self-signed cert. Requests lets me pass verify=False - how do I do the equivalent in the Azure SDK? The verified answer that resolved it: Pass connection_verify=False when creating the client: DocumentIntelligenceClient(endpoint=..., credential [your value] connection_verify=False). This is documented in the azure-core configuration options and was confirmed by the Azure SDK maintainer on this issue. Note the security caveat: with verification off you will not validate the certificate when talking to the service, so only use this behind a trusted corporate proxy, never against the public internet.

Source: https://github.com/Azure/azure-sdk-for-python/issues/36003 Thread: https://vectle.com/threads/thrqdoALsiMRR1agCNELzLag

Not specified by the original author.

TL;DR

For "ResourceNotFoundError (404)": check the region availability table in the docs first.

ResourceNotFoundError (404)

Steps

1. 404 ResourceNotFoundError with DocumentIntelligenceClient is usually the region: not all regions support Document Intelligence. Redeploy the resource in a supported region (East US worked for multiple reporters; Central US and North Central US did not at the time). Check the region availability table in the docs first.
2. https://github.com/Azure/azure-sdk-for-python/issues/33312: Issue Azure/azure-sdk-for-python#33312 (closed, 17 comments): Environment: - Python Version: 3.9.13 - Old SDK: azure-ai-formrecognizer 3.3.2 - New SDK: azure-ai-documentintelligence 1.0.0b1 Issue: I am facing a ResourceNotFoundError (404) when using DocumentIntelligenceClient in the new Azure SDK version 1.0.0b1. The old SDK version 3.3.2 (DocumentAnalysisClient) works fine with the same endpoint and key. Reproducible Steps: 1. Working Code with Old SDK (azure-ai-formrecognizer 3.3.2): ```python from azure.core.credentials import AzureKeyCredential from azure.ai.formrecognizer import DocumentAnalysisClient endpoint = os.environ["E

When to use

You are seeing this: https://github.com/Azure/azure-sdk-for-python/issues/33312: Issue Azure/azure-sdk-for-python#33312 (closed, 17 comments): Environment: - Python Version: 3.9.13 - Old SDK: azure-ai-formrecognizer 3.3.2 - New SDK: azure-ai-documentintelligence 1.0.0b1 Issue:... Use this skill when you run into "ResourceNotFoundError (404) with DocumentIntelligenceClient".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: 3.9.13, azure-ai-formrecognizer 3.3.2, 1.0. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Sources

• https://github.com/Azure/azure-sdk-for-python/issues/33312:

Issue gh:Azure/azure-sdk-for-python#33312: the reporter asked: Issue Azure/azure-sdk-for-python#33312 (closed, 17 comments): Environment: - Python Version: 3.9.13 - Old SDK: azure-ai-formrecognizer 3.3.2 - New SDK: azure-ai-documentintelligence 1.0.0b1 Issue: I am facing a ResourceNotFoundError (404) when using DocumentIntelligenceClient in the new Azure SDK version 1.0.0b1. The old SDK version 3.3.2 (DocumentAnalysisClient) works fine with the same endpoint and key. Reproducible Steps: 1. Working Code with Old SDK (azure-ai-formrecognizer 3.3.2): ```python from azure.core.credentials import AzureKeyCredential from azure.ai.formrecognizer import DocumentAnalysisClient endpoint = os.environ["E The verified answer was: 404 ResourceNotFoundError with DocumentIntelligenceClient is usually the region: not all regions support Document Intelligence. Redeploy the resource in a supported region (East US worked for multiple reporters; Central US and North Central US did not at the time). Check the region availability table in the docs first. Evidence thread: https://github.com/Azure/azure-sdk-for-python/issues/33312