DeleteUploadHandler API¶

Deletes an upload handler and discards its staged temporary file on the server. Use this to clean up if a chunked upload is cancelled or if an error occurs before the upload is finalized with UploadDocumentWithHandler.

Endpoint¶

/srv.asmx/DeleteUploadHandler

Methods¶

• GET /srv.asmx/DeleteUploadHandler?authenticationTicket=...&UploadHandler=...

• POST /srv.asmx/DeleteUploadHandler (form data)

• SOAP Action: http://tempuri.org/DeleteUploadHandler

Parameters¶

Response¶

Success Response¶

<response success="true" error="" />

Error Response¶

<response success="false" error="Error message" />

Required Permissions¶

Any authenticated user may call this API.

Chunked Upload Workflow¶

Upload handlers stage large files on the server before they are committed to the document library. DeleteUploadHandler is the cleanup step:

1. CreateUploadHandler -" Allocate a handler and obtain the UploadHandler GUID and ChunkSize.

2. UploadFileChunk -" Send the file in sequential chunks using the handler GUID.

3. UploadDocumentWithHandler (or UploadDocumentWithHandler1 / UploadNewDocumentWidthHandler) -" Finalize the upload and create the document or new version.

4. DeleteUploadHandler -" Call this only if the upload is cancelled or fails before step 3 completes. After a successful UploadDocumentWithHandler call the handler is consumed automatically and does not need to be deleted manually.

Example¶

GET Request¶

GET /srv.asmx/DeleteUploadHandler

  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

  &UploadHandler=a1b2c3d4-e5f6-7890-abcd-ef1234567890

HTTP/1.1

POST Request¶

POST /srv.asmx/DeleteUploadHandler HTTP/1.1

Content-Type: application/x-www-form-urlencoded

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301

&UploadHandler=a1b2c3d4-e5f6-7890-abcd-ef1234567890

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

               xmlns:tns="http://tempuri.org/">

  <soap:Body>

    <tns:DeleteUploadHandler>

      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>

      <tns:UploadHandler>a1b2c3d4-e5f6-7890-abcd-ef1234567890</tns:UploadHandler>

    </tns:DeleteUploadHandler>

  </soap:Body>

</soap:Envelope>

JavaScript¶

Every call answers XML with HTTP 200, success or not, so success is the thing to branch on and errorCode is the number to report.

async function call(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  const root = new DOMParser()
    .parseFromString(await response.text(), 'text/xml')
    .documentElement;

  if (root.getAttribute('success') !== 'true') {
    throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
  }
  return root;
}

Abandons an upload started with CreateUploadHandler and lets the server discard whatever was uploaded so far.

await call('DeleteUploadHandler', {
  authenticationTicket: ticket,
  UploadHandler: handler
});

Deleting the same handler twice is a success, not a 4041 - the operation is safe to call in a finally. A value that is not a GUID is refused 4000 before anything is looked up, with a message that says so and arrives in the caller's language. It used to be the untranslated literal bad Request.

Notes¶

• If the handler's temporary file does not exist (e.g. already cleaned up or never fully written), the call still returns success -" no error is raised.

• Passing a string that is not a valid GUID format returns an error immediately without performing any authentication check.

• Do not call DeleteUploadHandler after a successful UploadDocumentWithHandler -" the handler is consumed by the finalization step and the temporary file is already removed.

• Call DeleteUploadHandler if an error occurs at any point during UploadFileChunk or before UploadDocumentWithHandler is called, to free the temporary server storage.

Related APIs¶

• CreateUploadHandler - Allocate an upload handler and obtain the GUID and chunk size

• UploadFileChunk - Upload a single chunk of a file to an open handler

• UploadDocumentWithHandler - Finalize the upload and create or update a document

• DeleteDownloadHandler - Delete a download handler and discard its temporary file

Error Codes¶

The errorCode values this operation returns, checked against a running server: