---
cuppy_hub: azure
cuppy_path: reference/cosmos-db/errors.md
cuppy_section: docs
cuppy_doc: M49B-PH2G
cuppy_doc_uuid: f2f9a7f7-5eb1-4a0f-9a70-7c96a5ebb92f
cuppy_permalink: https://cuppy.io/azure/d/M49B-PH2G
cuppy_version: 1
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/azure/docs/reference/cosmos-db/errors
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: bdd10c3d340fe7b7951d5903d63d93d9c62d11d31167c385d4478288a30bfd70
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# Cosmos DB for NoSQL errors

In `@azure/cosmos`, a failed call throws `ErrorResponse`: `code` is the **HTTP status**, `substatus` the sub-code, plus `activityId` (give it to support), `retryAfterInMs`, `requestCharge` and `diagnostics`.

## 403 Forbidden

| Message / substatus | Cause → fix |
|---|---|
| `Request originated from client IP {...} through public internet.` / `… from client VNET through service endpoint.` / `… through private endpoint.` | The network path isn't allowed. If the path is unexpected, fix the client (service endpoint missing on the subnet, DNS resolving the public IP instead of the private endpoint); if expected, fix public access, IP, VNet or private endpoint settings. Changes take up to 15 minutes |
| `Request blocked by Auth : Request is blocked because principal [<id>] does not have required RBAC permissions to perform action [Microsoft.DocumentDB/databaseAccounts/readMetadata] on resource [/]. Learn more: https://aka.ms/cosmos-native-rbac.` (as reported on Microsoft Q&A) | No Cosmos data-plane role at that scope. Create a `sqlRoleAssignment` (Built-in Data Reader or Contributor); Azure RBAC roles, even Owner, don't help |
| `Forbidden (403); Substatus: 5300; The given request [PUT ...] cannot be authorized by AAD token in data plane.` / `Operation 'POST' on resource 'calls' is not allowed through Azure Cosmos DB endpoint` | Creating or deleting databases or containers (control plane) with an Entra token. Do it through Resource Manager (Bicep, CLI, management SDK) with Contributor or DocumentDB Account Contributor. Azure Functions Cosmos trigger: set `CreateLeaseContainerIfNotExists` to false and create the lease container yourself |
| `Response status code does not indicate success: Forbidden (403); Substatus: 1014` / `Partition key reached maximum size of {...} GB` | One logical partition is full (20 GB): redesign the key (hierarchical keys) |
| 403.3 | Write during a manual failover: SDKs follow the new write region; raw REST clients must re-read the account |
| 403 (other) | Expired token, storage quota reached, or a stored procedure blocked for high resource use |

## 429 Too many requests

| Kind | What to do |
|---|---|
| `Request rate is large. More Request Units might be needed, so no changes were made.` | The partition's RU/s are used up. **1–5% of requests as 429 with acceptable latency is healthy.** Otherwise look for a **hot partition** (one PartitionKeyRangeId near 100% normalized RU consumption while others idle): fix the key or spread the writes; then raise RU/s or use autoscale |
| `The request didn't complete due to a high rate of metadata requests.` | Too many database/container create, read or list calls (system-reserved RU budget). **More RU/s doesn't help**: cache clients and container references, back off |
| `The request didn't complete due to a transient service error.` | Retry; support case if it lasts minutes |

The SDK retries 429s itself, by default **up to 9 times within 30 seconds** (`connectionPolicy.retryOptions`), so the metric can show 429s your code never sees.

## Other status codes

| Status | Meaning → fix |
|---|---|
| 400 | Invalid JSON or query, missing required properties, a stronger consistency than the account allows, or **no partition key** on an operation that needs one |
| 401 | Invalid `Authorization` header (wrong key, bad token) |
| 404 (substatus 1013) | Item or resource doesn't exist; 1013 means a container create is still in progress: keep reading until 200 |
| 408 | A stored procedure, trigger or UDF ran too long |
| 409 | The `id` already exists **within that partition key value**: upsert, or treat as success when idempotent |
| 412 | ETag mismatch (optimistic concurrency): re-read and retry |
| 413 | Item over **2 MB** |
| 423 | Another throughput scale operation is running |
| 424 | Another operation in the same transactional batch failed |
| 449 | Transient write conflict: safe to retry |
| 503 | Service or network unavailable: safe to retry |

Customer-managed key accounts add substatus 4002 (Cosmos can't reach the key; restore its Key Vault access), 4003 (key deleted; recover it), 4005 (unwrap failed, often after rotation), 4006 (key URL includes a version) and 4009 (Key Vault name doesn't resolve).

## TypeScript with Entra ID

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { CosmosClient, ErrorResponse } from "@azure/cosmos";

// The identity needs a Cosmos DB data-plane role assignment (Built-in Data Contributor), not an Azure RBAC role.
const client = new CosmosClient({
  endpoint: `https://${process.env.COSMOS_ACCOUNT}.documents.azure.com:443/`,
  aadCredentials: new DefaultAzureCredential(), // the SDK asks for <endpoint>/.default
  connectionPolicy: { retryOptions: { maxRetryAttemptCount: 9, maxWaitTimeInSeconds: 30, fixedRetryIntervalInMilliseconds: 0 } },
});
const orders = client.database("shop").container("orders"); // partition key path: /customerId

type Order = { id: string; customerId: string; total: number };

export async function main(): Promise<void> {
  await orders.items.upsert<Order>({ id: "o-1001", customerId: "c-42", total: 12.5 });

  // Point read: id + partition key, the cheapest operation.
  const { resource } = await orders.item("o-1001", "c-42").read<Order>();
  console.log(resource?.total);

  // Parameterised query scoped to one partition.
  const { resources } = await orders.items
    .query<Order>(
      { query: "SELECT * FROM c WHERE c.customerId = @c AND c.total > @t", parameters: [{ name: "@c", value: "c-42" }, { name: "@t", value: 10 }] },
      { partitionKey: "c-42" },
    )
    .fetchAll();
  console.log(resources.length);

  try {
    await orders.items.create<Order>({ id: "o-1001", customerId: "c-42", total: 1 });
  } catch (e) {
    if (e instanceof ErrorResponse) {
      // code is the HTTP status (409 here); substatus and the activity ID matter for support cases
      console.error(e.code, e.substatus, e.activityId, e.retryAfterInMs);
      if (e.code !== 409) throw e;
    } else throw e;
  }
}
```

The account needs `disableLocalAuth: true` and a data-plane role for the identity: `reference/cosmos-db/access-and-modeling.md`. Create databases and containers in Bicep, not from the app.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 107 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/azure/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->