changeset 1221:69b41a9a2d7a

error payload
author Alain Mazy <am@orthanc.team>
date Mon, 17 Nov 2025 12:08:52 +0100
parents 04c433057467
children 14693db783a9
files Sphinx/source/users/rest.rst
diffstat 1 files changed, 144 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/Sphinx/source/users/rest.rst	Wed Nov 12 13:25:21 2025 +0100
+++ b/Sphinx/source/users/rest.rst	Mon Nov 17 12:08:52 2025 +0100
@@ -1041,7 +1041,7 @@
 Orthanc will propose the 120 most common SOP classes defined in the DCMTK library.
 If you know the resources you are going to retrieve contain uncommon SOP classes,
 you may provide a ``"SOPClassesInStudy"`` field in the payload.  In this case, Orthanc
-will only propose only these SOP classes during the association; provided that they are 
+will only propose these SOP classes during the association; provided that they are 
 accepted by Orthanc (see ``"AcceptedSopClasses"/"RejectedSopClasses"`` configurations)::
 
   $ curl --request POST --url http://localhost:8042/modalities/samples/get \
@@ -1057,6 +1057,149 @@
             }'
 
 
+DIMSE Error status (new in Orthanc 1.12.10)
+-------------------------------------------
+
+Starting with Orthanc 1.12.10, when performing C-Move, C-Get and C-Store
+operations, you can get access to the ``DIMSE Error Status`` and, possibly,
+to the instances ids that have been received during the C-Move or C-Get retrieve
+operations.
+
+For example, for a permissive ``C-Move`` or ``C-Get`` operation to retrieve 3 studies from a remote
+modality::
+
+  $ url -v http://localhost:8042/modalities/sample/move \
+    --data '{
+              "Permissive": true,
+              "Level" : "Study",
+              "TargetAet": "ORTHANC",
+              "Resources" : [
+                {"StudyInstanceUID" : "1.2.3"},
+                {"StudyInstanceUID" : "3.4.5"}
+              ]
+            }
+
+You'll get this type of response::
+  
+  {
+   "Description" : "REST API",
+   "Details" :
+   [
+      {
+         "DimseErrorStatus" : 0,
+         "Query" : {
+            "0008,0052" : "STUDY",
+            "0020,000d" : "1.2.3"
+         },
+         "ReceivedInstancesIds" :
+            ["ca58b590-8a115ed5-906f7f21-c7af8058-2637f722"]
+      },
+      {
+         "DimseErrorStatus" : 49152,
+         "Query" : {
+            "0008,0052" : "STUDY",
+            "0020,000d" : "3.4.5"
+         },
+         "ReceivedInstancesIds" : []
+      }
+   ],
+   "LocalAet" : "ORTHANC",
+   "Query" :
+   [
+      {
+         "0008,0052" : "STUDY",
+         "0020,000d" : "1.2.3"
+      },
+      {
+         "0008,0052" : "STUDY",
+         "0020,000d" : "3.4.5"
+      }
+   ],
+   "RemoteAet" : "SAMPLE",
+   "TargetAet" : "ORTHANC"
+  
+If you are creating an asynchronous operation, you'll get the same detailed
+information in the ``Content.Details`` field of the job.
+
+If you are running a non-permissive operation (default), for example, a ``C-Get``::
+
+  $ curl -v http://localhost:8042/modalities/sample/get \
+    --data '{
+              "Permissive": false,
+              "Level" : "Study",
+              "Resources" : [
+                {"StudyInstanceUID" : "1.2.3"},
+                {"StudyInstanceUID" : "3.4.5"}
+              ]
+            }
+
+If one of the resource is missing, you'll get a ``RetrieveJob`` error payload
+in the HTTP response::
+  
+  {
+    "Details" : "C-GET SCU to AET \"SAMPLE\" has failed with DIMSE status 0xC000",
+    "ErrorPayload" :
+    {
+      "Content" :
+      [
+        {
+          "DimseErrorStatus" : 0,
+          "Query" : {
+            "0008,0052" : "STUDY",
+            "0020,000d" : "1.2.3"
+          },
+          "ReceivedInstancesIds" :
+            ["ca58b590-8a115ed5-906f7f21-c7af8058-2637f722"]
+        },
+        {
+          "DimseErrorStatus" : 49152,
+          "Query" : {
+            "0008,0052" : "STUDY",
+            "0020,000d" : "3.4.5"
+          },
+          "ReceivedInstancesIds" : []
+        }
+      ],
+      "Type" : "RetrieveJob"
+    },
+    "HttpError" : "Internal Server Error",
+    "HttpStatus" : 500,
+    "Message" : "Error in the network protocol",
+    "Method" : "POST",
+    "OrthancError" : "Error in the network protocol",
+    "OrthancStatus" : 9,
+    "Uri" : "/modalities/sample/get"
+  }
+
+If you are running a non-permissive ``C-Store`` operation that fails, for example::
+
+  $ curl -v http://localhost:8042/modalities/sample/store \
+    --data '{
+              "Resources" : ["595df1a1-74fe920a-4b9e3509-826f17a3-762a2dc3"]
+            }
+
+You'll get a simple ``Dimse`` error payload like::
+
+  {
+    "Details" : "C-STORE SCU to AET \"SAMPLE\" has failed with DIMSE status 0xA700",
+    "ErrorPayload" :
+    {
+      "Content" :
+      {
+        "DimseErrorStatus" : 42752
+      },
+      "Type" : "Dimse"
+    },
+    "HttpError" : "Internal Server Error",
+    "HttpStatus" : 500,
+    "Message" : "Error in the network protocol",
+    "Method" : "POST",
+    "OrthancError" : "Error in the network protocol",
+    "OrthancStatus" : 9,
+    "Uri" : "/modalities/sample/store"
+  }  
+
+
 
 Performing Query/Retrieve (C-Find)
 ----------------------------------