diff --git a/src/content/docs/developer/modules/ui-modules/custom-mt.mdx b/src/content/docs/developer/modules/ui-modules/custom-mt.mdx
index d645f366..463cc83e 100644
--- a/src/content/docs/developer/modules/ui-modules/custom-mt.mdx
+++ b/src/content/docs/developer/modules/ui-modules/custom-mt.mdx
@@ -322,6 +322,22 @@ Response payload example:
 }
 ```
 
+The `translations` array must be nested under the top-level `data` object. A response that returns the array at the top level (for example, `{"translations": [...]}`) is treated as containing no translations and is rejected.
+
+Return exactly one translation per source string, in the same order as the strings were received. Crowdin matches translations to source strings by their position in the array, not by identifier. If the number of returned translations does not match the number of strings sent, that batch is skipped.
+
+For large payloads, you can return a `translationsUrl` instead of the inline `translations` array:
+
+```json
+{
+  "data": {
+    "translationsUrl": "https://app.example.com/jKe8ujs7a-translations.ndjson"
+  }
+}
+```
+
+`translationsUrl` is a public URL to a [new-line delimited json](https://github.com/ndjson/ndjson-spec) file with the translated strings. Use either `translations` or `translationsUrl`.
+
 ## Expected Response from the App (With errors)
 
 Response payload example:
@@ -335,3 +351,16 @@ Response payload example:
 ```
 
 The structure of the responses from the app should correspond to the presented examples, otherwise Crowdin will consider them invalid.
+
+## Troubleshooting
+
+If the Custom MT app returns a response but translations are not saved, the response body most likely does not match the expected schema. When a response is rejected, Crowdin includes the received status code and body in the error message, so you can compare it against the schema above.
+
+| Error message                                 | Likely cause                                                                                                              | How to fix                                                                                                                                        |
+|-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| Custom MT engine returned no translations     | The `translations` array is missing, empty, or placed outside the `data` object (for example, returned at the top level). | Nest the `translations` array under the `data` object and make sure it is not empty.                                                              |
+| Custom MT engine returned invalid translation | One of the elements in the `translations` array is not a string.                                                          | Return each translation as a plain string.                                                                                                        |
+| Custom MT engine returned unexpected response | The response body is not valid JSON.                                                                                      | Return a well-formed JSON body that matches the expected schema.                                                                                  |
+| Custom MT engine returned HTTP error          | The endpoint responded with a non-2xx HTTP status code.                                                                   | Return HTTP 200 for successful translations, and use the [error response format](#expected-response-from-the-app-with-errors) to report failures. |
+
+Some responses are rejected without an error message. If the number of returned translations does not match the number of source strings sent, Crowdin skips that batch and leaves those strings untranslated. Make sure your app returns exactly one translation per source string, in the same order.