SDK Error Codes
Useful for troubleshooting SDK when it throws error. Be familiar and try to remember the common errors.
Status Code Error
https://learn.microsoft.com/en-us/rest/api/cosmos-db/http-status-codes-for-cosmosdb
| Code |
Title |
Reason |
| 400 |
Bad Request |
Something was wrong with the item in the body of the request |
| 403 |
Forbidden |
Container was likely full |
| 408 |
Request timeout |
The operation didn't complete within the allotted amount of time. This code is returned when a stored procedure, trigger, or UDF (User Defined Function) within a query doesn't complete execution within the maximum execution time. |
| 409 |
Conflict |
Item in container likely already had a matching id |
| 413 |
RequestEntityTooLarge |
Item exceeds max entity size. 2MB for Cosmos, 16MB for Mongo. |
| 424 |
Failed dependency |
One of the batch item fail, all other will fail hence it just return 424 |
| 429 |
TooManyRequests |
Current request exceeds the maximum RU/s provisioned for the container. Also in Bounded Staleness if it exceeded K or T |
| 449 |
Concurrency Error |
Returned during optimistic concurrency control when a write operation fails because the document was modified by another request since it was last read (the _etag did not match). |
| 500 |
Internal Server Error |
The operation failed because of an unexpected service error. Contact support. |
| 503 |
Service Unavailable |
The operation couldn't be completed because the service was unavailable. This situation could happen because of network connectivity or service availability issues. It's safe to retry the operation. If the issue persists, contact support. |
In npm there is a way to view:
- x-ms-request-charge = to view charges
- etag = to view version
Transient Errors
Transient error means temporary (solve by retry) error. Cosmosdb normally throws error 503 in such situations.
If you're noticing 429 exceptions happening, you might also notice 503 errors being reported in the Insights->Request Total Request by Status Code charts. These exceptions could indicate that the 429 exceptions are happening because of transient service errors.
| Feature |
Description |
| Root Cause |
Network connectivity issues, momentary hardware failure, service maintenance, or system load balancing (failover/reconfiguration). |
| Common HTTP Codes |
408 (Request Timeout), 503 (Service Unavailable), and various connectivity-related errors. |
| Handling |
Applications that connect to the cloud must be built to expect these errors. The recommended pattern is retry logic with exponential backoff. |
| The "Why" |
The service is there, but a temporary event |
Good to know errors
Document create error
| Status Code |
Operation Type |
Description |
| 201 |
Created |
The operation was successful. |
| 400 |
Bad Request |
The JSON body is invalid. |
| 403 |
Forbidden |
The operation couldn't be completed because the storage limit of the partition was reached. |
| 409 |
Conflict |
The partition key and id provided for the new document has been taken by an existing document. |
| 413 |
Entity Too Large |
The document size in the request exceeded the allowable document size. |
Readfeed error
| Status Code |
Operation Type |
Description |
| 400 |
Bad Request |
The override set in x-ms-consistency-level is stronger than the one set during account creation. For example, if the consistency level is Session, the override can't be Strong or Bounded. |
Document update
| Status Code |
Operation Type |
Description |
| 400 |
Bad Request |
The JSON body is invalid. Check for missing curly brackets or quotes. |
| 404 |
Not Found |
The document no longer exists, that is, the document was deleted. |
| 409 |
Conflict |
The partition key and id provided for the new document has been taken by an existing document. |
| 413 |
Entity Too Large |
The document size in the request exceeded the allowable document size. |
Patching document
| Status Code |
Operation Type |
Description |
| 400 |
Bad Request |
The JSON body is invalid. |
| 412 |
Precondition Failed |
The specified precondition isn't met. |
Query
| Sub Status Code |
Status Code |
Operation Type |
Description |
| 1002 |
404 |
Not found |
Partition Key is not matching, value might be found but wrong partition key |
Retries
- One of the best methods it to have exponential backoff, which is to increase the wait time between retries.
- Retries are for transient errors, not for bad requests.
- SDK do not do retry automatically for Write for network timeouts (408) and Service Unavailable (503) errors. Read retries for 408 and 503.
4.Read and Write automatically retried for Throttling (429), Concurrency (449).
Log tables
This section suppose to be under troubleshooting.
The NoSQL API log tables are:
- DataPlaneRequests - This table logs back-end requests for operations that execute create, update, delete, or retrieve data.
- QueryRuntimeStatistics - This table logs query operations against the NoSQL API account.
- PartitionKeyStatistics - This table logs logical partition key statistics in estimated KB. It's helpful when troubleshooting skew storage.
- PartitionKeyRUConsumption - This table logs every second aggregated RU/s consumption of partition keys. It's helpful when troubleshooting hot partitions.
- ControlPlaneRequests - This table logs Azure Cosmos DB account control data, for example adding or removing regions in the replication settings.