Data Stores Troubleshooting

---

Quick Check

In order:

1. Account state - does the account show Live in Environment → Databases?
2. The container list - do your containers appear under Manage containers on the Database node?
3. The container's API settings - are the operations you are calling switched on for that container?

---

Common Issues

The account provisioned, but reads and writes are refused

Symptoms:

• The account shows Live
• Listing containers works, but reading or writing documents fails
• The API answers DATA_PLANE_FORBIDDEN

What is happening:

Azure separates managing a resource from reaching the data inside it. The role that creates a CosmosDB account gives no access to documents at all - document access is a separate role assignment on the account. This is why a successful provision tells you nothing about whether a write will succeed, and why listing containers can work while every document read fails.

Fix: re-deploy the data store. That re-runs the provisioning step which grants document access.

---

Reads are slow or rejected under load

Symptoms:

• Requests succeed sometimes and fail other times
• Failures cluster when traffic is heavy
• The API answers THROTTLED

What is happening: the account is rate-limiting your workspace. This is the most common CosmosDB failure, and it is not a connectivity problem.

Fix: retry the request. If it persists, raise the scaling profile on the account or the database.

---

Documents I know exist come back empty

Symptoms:

• A read returns nothing
• No error is reported
• A document you wrote moments ago is not returned

What is happening: the query is looking in the wrong partition. A partition key that does not match how the documents were written does not produce an error. It produces an empty result, which reads as missing data.

Fix: check the container's partition key path against the field your documents actually carry. The partition key cannot be changed after the container is created, so a genuine mismatch means creating a new container and moving the data.

---

Updates and deletes fail with 400 on a table that otherwise works

Symptoms:

• GET and POST on the table work
• PUT and DELETE on a single document are refused with 400
• The API answers PARTITION_KEY_REQUIRED

What is happening: Cosmos addresses a document by id and partition key together. On a table partitioned on anything other than /id, that value has to be supplied, and the platform will not guess it.

Fix: pass it as a query parameter.

DELETE /oi-api/data-stores/{store}/databases/{database}/tables/{table}/{documentId}?partitionKey=VALUE

---

Manage containers shows no containers

Symptoms:

• The container picker is empty
• The account exists in the workspace

Common causes:

• The account has not finished provisioning - look for Live rather than Provisioning
• The database record points at an account that no longer exists (STORE_NOT_FOUND)

---

An operation I turned off still shows in the API Explorer

This is expected. All four document endpoints are listed for every table regardless of the toggles. The toggle is checked when the request arrives, not when the listing is built.

Calling an operation that is turned off returns 403 with OPERATION_NOT_EXPOSED. If you meant it to be open, re-enable it on the table in Configure Database - see Database Tables.

---

I removed the container record and the container is still there

This is correct behaviour.

For a container that really was provisioned, the platform refuses rather than reporting a delete it did not perform. Delete the container in the Azure portal first, then remove the record.

Deleting a document is different. That one is honoured, and it does remove data.

---

Requests return 401

Your token is missing or has expired. Generate a new JWT from the API Keys menu, or from the authentication panel in the API Explorer.

---

Error Reference

Code	Means	Do this
DATA_PLANE_FORBIDDEN	Account access granted, document access not	Re-deploy the data store
THROTTLED	The account is rate-limiting the workspace	Retry, or raise the scaling profile
PARTITION_KEY_REQUIRED	A single-document call needs the partition key	Add ?partitionKey=
OPERATION_NOT_EXPOSED	The surface owner turned this operation off	Re-enable it on the table, if that was not intended
SURFACE_NOT_FOUND	No such surface in this workspace	Check the surface lookup in the path
TABLE_NOT_FOUND	No such table in that database	Check the container name
TABLE_NOT_EXPOSED	The table is not activated on this surface	Activate it in Configure Database
STORE_NOT_FOUND	The record points at an account that is gone	Re-point or recreate the account
STORE_NOT_PROVISIONED	The record exists but was never provisioned	Save and provision it
DOCUMENT_TOO_LARGE	The document exceeds what the container accepts	Keep the payload elsewhere and store a pointer
CONFLICT	A document with that id already exists	Use update rather than create
UNREACHABLE	Nothing answered at all	Check the account state, then retry
UNRECOGNISED	The store refused and did not say why	Retry; if it persists, raise it with support

---

Ask Azi

---

Related

Topic	Guide
Provisioning an account	CosmosDB Setup
Containers and data classes	Database Management
Surface tables and operations	Database Tables
Endpoint reference	REST API