[DH-5527] Document error codes

README.md

@@ -314,7 +314,7 @@ curl -X 'POST' \
 }'
 ```
 
-### Run scripts
+### How to migrate data between versions
 Our engine is under ongoing development and in order to support the latest features, we provide scripts to migrate the data from the previous version to the latest version. You can find all of the scripts in the `dataherald.scripts` module. To run the migration script, execute the following command:
 
 ```

docs/api.create_database_connection.rst

@@ -104,12 +104,20 @@ HTTP 201 code response
       }
     }
 
-HTTP 400 code response (if the db connection fails it returns a 400 error)
+HTTP 400 code response (if the db connection fails it returns a 400 error), :doc:`here <api.error_codes>` you can find
+all the error codes
 
 .. code-block:: rst
 
     {
-        "detail": "string"
+      "error_code": "string",
+      "message": "string",
+      "description": "string",
+      "detail": {
+        "alias": "string",
+        "use_ssh": false,
+        "connection_uri": "string"
+      }
     }
 
 **Example 1**

docs/api.error_codes.rst

@@ -0,0 +1,50 @@
+Error Codes
+=============================
+
+When encountering errors in the API, an error code and a brief explanation are provided,
+along with a 400 HTTP status code, following this structure:
+
+.. code-block:: rst
+
+    {
+        "error_code": "<error_code>",
+        "message": <error_message>,
+        "description": <description>,
+        "detail": {
+            <body_params>
+        }
+    }
+
+**Error Codes:**
+
+DB Connections
+
+- `invalid_database_connection` - Unable to establish the database connection.
+- `invalid_database_uri_format` - The `connection_uri` doesn't have the correct format.
+- `ssh_invalid_database_connection` - The SSH connection failed.
+- `empty_database` - Although the connection was established, there are no tables present.
+- `database_connection_not_found` - Database resource could not be found.
+
+Golden SQL
+
+- `golden_sql_not_found` - Golden SQL resource not found.
+- `invalid_golden_sql` - The Golden SQL doesn't have the correct format.
+
+Finetuning Model
+
+- `llm_model_not_supported` - The specified model is not supported.
+
+SQL Generation
+
+- `prompt_not_found` - Prompt resource not found.
+- `sql_generation_not_created` - The SQL generation failed.
+- `sql_injection` - The generated/provided SQL failed the injection validation.
+- `sql_generation_not_found` - SQL generation resource not found.
+
+NL Generation
+
+- `nl_generation_not_created` - The NL generation failed.
+
+**Other Errors**
+
+- `invalid_object_id` - The provided string is not a valid ObjectId.

docs/api.rst

@@ -225,6 +225,26 @@ Related endpoints are:
         "metadata": "dict | None" // Optional, default None
     }
 
+Error Codes
+---------------------
+Certain errors are accompanied by an error code and an explanatory message. These errors trigger an HTTP 400 response
+code.
+
+**DB connection error code response example:**
+
+.. code-block:: json
+
+    {
+      "error_code": "invalid_database_uri_format",
+      "message": "Invalid URI format: foo",
+      "description": null,
+      "detail": {
+        "alias": "foo",
+        "use_ssh": false,
+        "connection_uri": "gdfgdgAABl5e-dfg_-wErFJdFZeVXwnmew_dfg__WU-dfgdfa=="
+      }
+    }
+
 .. toctree::
     :hidden:
 
@@ -268,3 +288,5 @@ Related endpoints are:
     api.cancel_finetuning
     api.delete_finetuning
     api.list_finetunings
+
+    api.error_codes

docs/api.update_database_connection.rst

@@ -54,12 +54,20 @@ HTTP 200 code response
       }
     }
 
-HTTP 400 code response (if the db connection fails it returns a 400 error)
+HTTP 400 code response (if the db connection fails it returns a 400 error), :doc:`here <api.error_codes>` you can find
+all the error codes
 
 .. code-block:: rst
 
     {
-        "detail": "string"
+      "error_code": "string",
+      "message": "string",
+      "description": "string",
+      "detail": {
+        "alias": "string",
+        "use_ssh": false,
+        "connection_uri": "string"
+      }
     }
 
 **Example 1**