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 - is API enabled on, and is the method you are calling switched on?
4. Your access right - do you hold the Workspace.DataStore.Table.* right for that method?

The account is live, but documents are refused

Symptoms: the account shows Live; listing containers works, but reading or writing documents fails with DATA_PLANE_FORBIDDEN.

Azure separates managing a resource from reaching the data inside it. The role that creates a CosmosDB account gives no access to documents; document access is a separate role assignment on the account, made by a later provisioning step. If that step has not completed, the account exists and every document call is refused.

Fix: save the account again with Save & Apply in Environment -> Databases (the product calls this re-deploying the data store). That re-runs the step that grants document access.

Reads are slow or rejected under load

Symptoms: requests succeed sometimes and fail other times, mostly when traffic is heavy, with THROTTLED (429).

The account is rate-limiting your workspace. This is not a connectivity problem.

Fix: retry after the time the response gives. If it persists, choose a higher scaling profile for the account.

Documents I know exist come back empty

Symptoms: a read returns nothing, no error is reported, and a document you wrote moments ago is not returned.

The read 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.

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 real mismatch means creating a new container and moving the documents.

A single-document call fails with 400

Symptoms: listing and creating work, but a read, update or delete of one document is refused with 400 PARTITION_KEY_REQUIRED.

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 OpenX will not guess it.

Fix: pass it as a query parameter:

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

Manage containers shows no containers

Common causes:

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

"The account it pointed at is gone" and "no account was ever chosen" are different problems with different fixes. The API tells them apart; the empty list does not.

An operation I expected is missing from the API Manager

This is expected when it is switched off. /ox-api/openapi and the API Manager list, for each container, only the methods it publishes, and only those your access rights let you see. Switch the method on in Manage containers (see Table endpoints), or ask for the right.

A client that calls a method that is switched off anyway is refused with 403 OPERATION_NOT_EXPOSED.

I removed a container and it is still there

This is correct. A container that already exists in its Cosmos account is refused rather than removed, because the copy of its documents that must be taken first is not switched on yet:

This container exists in its Cosmos account, and the copy of its documents that must be taken before it is removed is not switched on yet. Until it is, the record is kept rather than removed while the documents stay.

Only a container that was never provisioned can be removed today; it has nothing in Azure and goes when you save. See A removal was refused. Deleting a document is different: that is honoured, and it removes the data.

Requests return 401

Your token is missing, malformed or expired; the answer is "This request could not be authorized." Generate a new key from APIs -> API Keys.

Error reference

Code	Status	Means	Do this
DATA_STORE_RIGHT_MISSING	403	You do not hold the access right this method needs	Ask a member who can grant it (see Team & Access Rights)
DATA_PLANE_FORBIDDEN	403	The account exists, but its document access has not been granted yet	Save the account again with Save & Apply
THROTTLED	429	The account is rate-limiting the workspace	Retry, or choose a higher scaling profile
PARTITION_KEY_REQUIRED	400	A single-document call needs the partition key	Add ?partitionKey=
OPERATION_NOT_EXPOSED	403	That method is not switched on for the container	Switch it on in Manage containers, if intended
TABLE_NOT_EXPOSED	404	The container publishes no API	Switch API enabled on in Manage containers
TABLE_NOT_FOUND	404	No such table in that database	Check the container name
DATABASE_NOT_FOUND	404	No such database in this workspace	Check the database in the path
DATABASE_NOT_IN_STORE	404	That database is not in the store named in the path	Use the store that owns the database
STORE_NOT_FOUND	404	There is no data store by that name in this workspace	Re-point or recreate the account
STORE_NOT_PROVISIONED	409	The record exists but was never provisioned	Save its configuration to provision it
DOCUMENT_TOO_LARGE	413	The document exceeds what the container accepts	Keep the payload elsewhere and store a pointer
CONFLICT	409	A document with this id already exists in this partition	Update it instead of creating it
UNREACHABLE	504	Nothing answered at all	Check the account state, then retry
UNRECOGNISED	502	The store refused and did not say why	Retry; if it persists, contact support

UNREACHABLE means nothing answered. Every other code means something did answer, which is why they are reported separately instead of all being called connectivity failures.

Related

Topic	Guide
Provisioning an account	CosmosDB Setup
Containers and data classes	Containers
Endpoints and operations	Table endpoints