Azure Cosmos DB is a highly-scalable distributed database service. The nature of Cosmos DB means that sometimes requests will return HTTP status codes in the 400 range when operations do not succeed. Blue Matador automatically monitors the number of requests with each status code using the TotalRequests metric so you can debug your usage of Cosmos DB and correlate issues with other events in your system. This document contains information for the following 4xx Status Codes:

    HTTP 400 (Bad Request)

    A Bad Request typically means that the request body is malformed. Cosmos DB uses JSON, SQL, or JavaScript and requests must match the language used by the backing database. A 400 could also be returned when doing a GET operation that uses a lower consistency level than the configured one on the account. Another case that can result in a 400 response is not including a partition key when inserting an item. In all cases, the only course of action is to figure out which operations are resulting in a 400 by using application logs or other metrics and fix them.


    HTTP 401 (Unauthorized)

    An Unauthorized request means the Authorization header for the request is invalid. This can be caused by issues with the client that is used to make requests. Check for any changes to the code that constructs your requests to Cosmos DB to determine if a bug was introduced.


    HTTP 403 (Forbidden)

    A Forbidden response has multiple causes. If the Authorization token used in the request is expired, a 403 will be returned. Most clients will refresh these tokens automatically, so 403’s from this source may be transient.

    A 403 can also be returned when doing a POST operation on a resource that has reached some kind of limit. Cosmos DB automatically raises these limits in most cases, but if this type of 403 is common you should contact Azure Support.

    Firewall rules that block external requests to Cosmos DB will also result in 403 responses. If you are in control of these requests, either modify your firewall rules to allow them or stop making the requests so that these 403 responses do not mask other possible 403 issues.

    A 403.3 is returned when doing a write operation during a failover. Your client should catch these and direct writes to the new write endpoint. These should stop occurring after the failover is complete.


    HTTP 404 (Not Found)

    A Not Found error occurs when performing an operation on a resource that no longer exists. This can include items, collections, or databases depending on the backing database used for the Cosmos DB Account. 


    HTTP 408 (Request Timeout)

    Request Timeout means the request did not complete in time. This can happen when a stored procedure, trigger, or UDF within a query takes too long. You can minimize the impact of 408 errors by optimizing or removing your stored procedures, triggers, and UDFs.


    HTTP 409 (Conflict)

    A Conflict means that the ID for an item has already been taken. For partitioned collections, the ID must be unique within the partition. Modify your requests to ensure that IDs are unique for each partition.


    HTTP 413 (Entity Too Large)

    Entity Too Large means the document size in the request is higher than the 2MB limit. Modify your requests to use smaller document sizes to avoid this issue.


    HTTP 429 (Too Many Requests)

    The request has exceeded the provisioned throughput. The request can be retried, and this retry is automatically handled by many Cosmos DB clients. A 429 error can occur even if your total consumed Request Unit (RU) is below the provisioned amount due to the distributed nature of Cosmos DB. Some amount of throttled requests must be expected and handled by your application. The number of throttles can be greatly increased due to hot partitions. For more information on adjusting Cosmos DB throughput, refer to this document.