HTTP Status Codes for Azure Cosmos DB

This article provides the HTTP status codes returned by the REST operations.

Code Description
200 OK One of the following REST operations were successful:

- GET on a resource.
- PUT on a resource.
- POST on a resource.
- POST on a stored procedure resource to execute the stored procedure.
201 Created A POST operation to create a resource is successful.
204 No Content The DELETE operation is successful.
400 Bad Request The JSON, SQL, or JavaScript in the request body is invalid.

In addition, a 400 can also be returned when the required properties of a resource are not present or set in the body of the POST or PUT on the resource.

400 is also returned when the consistent level for a GET operation is overridden by a stronger consistency from the one set for the account.

400 is also returned when a request that requires an x-ms-documentdb-partitionkey does not include it.
401 Unauthorized 401 is returned when the Authorization header is invalid for the requested resource.
403 Forbidden The authorization token expired.

403 is also returned during a POST to create a resource when the resource quota has been reached. An example of this is when trying to add documents to a collection that has reached its provisioned storage.

403 can also be returned when a stored procedure, trigger, or UDF has been flagged for high resource usage and blocked from execution.

403 forbidden error is returned when the firewall rules configured on your Azure Cosmos DB account block your request. Any requests originating from machines outside the allowed list will receive a 403 response.

403.3 – This status code is returned for write requests during the manual failover operation. This status code is used as redirection code by drivers to forward the writes to new write region. Direct REST client must perform GET on DatabaseAccount to identify the current write region and forward the write request to that endpoint.
404 Not Found The operation is attempting to act on a resource that no longer exists. For example, the resource may have already been deleted.
408 Request Timeout The operation did not complete within the allotted amount of time. This code is returned when a stored procedure, trigger, or UDF (within a query) does not complete execution within the maximum execution time.
409 Conflict The ID provided for a resource on a PUT or POST operation has been taken by an existing resource. Use another ID for the resource to resolve this issue. For partitioned collections, ID must be unique within all documents with the same partition key value.
412 Precondition Failure The operation specified an eTag that is different from the version available at the server, that is, an optimistic concurrency error. Retry the request after reading the latest version of the resource and updating the eTag on the request.
413 Entity Too Large The document size in the request exceeded the allowable document size for a request. The max allowable document size is 2 MB.
429 Too Many Request The collection has exceeded the provisioned throughput limit. Retry the request after the server specified retry after duration. For more information, see request units.
449 Retry With The operation encountered a transient error. This code only occurs on write operations. It is safe to retry the operation.
500 Internal Server Error The operation failed due to an unexpected service error. Contact support. See Filing an Azure support issue.
503 Service Unavailable The operation could not be completed because the service was unavailable. This situation could happen due to network connectivity or service availability issues. It is safe to retry the operation. If the issue persists, contact support.

See also