Learn how to handle Cosmos DB MongoDB API error codes. Our MongoDB Support team is here to help you with your questions and concerns.

Handling Cosmos DB MongoDB API Error Codes

Azure Cosmos DB, a fully managed NoSQL database service, supports MongoDB APIs. However, developers often run into error codes unique to this implementation. These error codes help diagnose and resolve issues efficiently. Today, we will look at the common error codes and how to troubleshoot them effectively.

Common Error Code Categories

• Connection Errors:
  • 40007: Connection timeout.
  • 40107: Connection refused.
  • 40307: Connection closed by peer.
  • 40607: Authentication failed.
• Command Errors:
  • 40000: Invalid command.
  • 40100: Command not supported.
  • 40200: Command failed.
  • 40300: Command timed out.
• Document Errors:
  • 40000: Invalid document.
  • 40100: Document not found.
  • 40200: Document already exists.
  • 40300: Document write error.
• Index Errors:
  • 40000: Invalid index.
  • 40100: Index not found.
  • 40200: Index creation failed.
  • 40300: Index deletion failed.
• Database Errors:
  • 40000: Invalid database.
  • 40100: Database not found.
  • 40200: Database creation failed.
  • 40300: Database deletion failed.
• Additional Error Codes:
  • 40400: Resource not found.
  • 40500: Operation not permitted.
  • 40600: Invalid request.
  • 40700: Internal server error.

Detailed Error Explanations and Fixes

• 11000 – Duplicate Key Error

  Triggered when attempting to insert a document with a unique field value (e.g., `_id`) that already exists.

  Fix: Ensure unique values for the `_id` or other unique fields before insertion.
• 16500 – Request Rate Is Large (Throttling)

  This error code indicates the request exceeds the available Request Units (RUs).

  Fix: Increase RU/s allocation or implement retry logic to handle throttling.
• 2 – BadValue

  Occurs when an invalid argument is passed to a MongoDB command.

  Fix: Validate all arguments, data types, and query syntax before execution.
• 13 – Unauthorized

  Results from incorrect credentials, missing permissions, or access issues.

  Fix: Verify authentication details and ensure sufficient permissions for the operation.
• 7 – NotWritablePrimary

  Indicates an operation requiring a primary write is directed to a non-writable replica.

  Fix: Ensure the operation targets the primary write region or writable instance.
• 6 – HostUnreachable

  This error indicates network or region-specific connectivity issues.

  Fix: Check network settings and confirm the endpoint/region in the connection string.
• 50 – ExceededTimeLimit

  Triggered when an operation exceeds the allowed execution time.

  Fix: Optimize queries and allocate sufficient RUs to reduce execution time.
• 16 – IllegalOperation

  Thrown for unsupported MongoDB commands.

  Fix: Refer to Cosmos DB’s documentation to avoid unsupported operations.
• 202 – WriteConflict

  Indicates simultaneous write operations on the same document.

  Fix: Implement retry logic to resolve conflicts.
• 43 – CursorNotFound

  It occurs when a cursor expires or is invalid.

  Fix: Use cursors promptly and handle timeouts gracefully in your application logic.
• 121 – Document Validation Failure

  Thrown when a document fails to meet the collection’s validation schema.

  Fix: Ensure documents adhere to schema rules, updating schema or correcting documents as needed.

Best Practices for Error Handling

• For transient errors like 16500 (Throttling) or 202 (WriteConflict), use exponential backoff strategies to retry operations after short delays, improving resilience.
• Create efficient queries leveraging indexes and limiting data retrieval. Avoid expensive operations and refine query filters for better performance.
• Regularly track Request Unit usage for the database and collections. Scale up throughput as needed to handle increasing workloads effectively.

[Need assistance with a different issue? Our team is available 24/7.]

Conclusion

By understanding Cosmos DB’s MongoDB API error codes and applying the troubleshooting tips outlined above, we can ensure smoother application performance and robust error handling.

In brief, our Support Experts demonstrated how to handle Cosmos DB MongoDB API error codes.