Errors and Status Codes

A request to the DocumentProcessing Web API that fails returns an HTTP status code and, depending on the cause, a message in one of four forms: a JSON string, plain text, a JSON object with validation errors or an empty body. The status codes and messages below were observed on DS Server 5.0.2, together with the causes the endpoint reference lists, so that your application can tell a missing license from an expired token or a malformed request and react to each.

Status Codes at a Glance

Only a 200 answer holds a result, so check the status before you decode the response.

DS Server Is Not Registered

Until DS Server is licensed, every DocumentProcessing endpoint answers 400 Bad Request with this message:

DS Server is not registered.

The Web API creates no trial output and no documents with a watermark: without a license, it creates no documents at all. Register the server with a serial number in the admin portal, as Licensing shows. The Document Editor and the Document Viewer show the same message on an unregistered server.

The message comes in two content types, depending on the endpoint:

Read the body as text and remove the quotes when the content type is JSON, so that one comparison works for both.

DS Server checks the license before it checks the values of the parameters. An unknown barcode type or return format also gets "DS Server is not registered." on an unregistered server, so the errors described in Errors of the Endpoints appear only once the server is registered. Validation errors of the JSON body and of the parameter types come first, as the next section describes.

Validation Errors

A body or a parameter that can't be read as the type the endpoint expects is refused with 400 and a problem details object, a JSON object whose type points to RFC 9110, before the license check. For example, the convert endpoint expects the document as a JSON string, and a JSON object as its body gives:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "$": [
      "The JSON value could not be converted to System.String. Path: $ | LineNumber: 0 | BytePositionInLine: 1."
    ]
  },
  "traceId": "00-98bb1d86ed54a2b27c74e70ef8de604f-8ebe2856831ddc90-00"
}

errors names what could not be read: $ is the whole body, $.documentAccessPermissions a property of the body, and a name without $, such as zoomFactor, a query parameter. Typical causes:

• A JSON object where the endpoint expects a string, or the reverse. The convert, info and thumbnails endpoints and the three PDF reading endpoints take the document as a JSON string alone. The merge, append, find-and-replace, pdf/create and barcodes/create endpoints take a JSON object.
• A value of the wrong type in the body, such as a string for a number or a name for an enumeration. For example, documentAccessPermissions of pdf/create takes a number, and "AllowAll" gives "The JSON value could not be converted".
• A query parameter that is not a valid number or Boolean, such as zoomFactor=abc or flattenFormFields=maybe, which gives "The value 'abc' is not valid.".

Properties of the body that an endpoint doesn't know are ignored without an error. A misspelled property name therefore doesn't fail the request, but its setting has no effect.

Errors of the Endpoints

Once DS Server is registered, the endpoints check the document and the parameters. The endpoint reference lists these causes of 400 Bad Request:

The pages of the endpoints under DocumentProcessing give the cause for each endpoint. For pdf/metadata and pdf/acroforms/fields, a 400 can mean that the PDF has no metadata or no form fields, not that the request is wrong.

Access Token Errors

When OAuth is enabled in the admin portal, DS Server checks the access token of every request and answers 401 Unauthorized with an empty body:

Request a new token and send the request again. If the new token is refused as well, check the expiry date of the security profile in the admin portal, as Creating Security Profiles shows: DS Server still issues tokens for an expired profile, but accepts none of them.

When OAuth is disabled, which is the default of a new installation, DS Server checks no token: a request with an invalid token or without one reaches the endpoint. Enable OAuth switches the check on.

The token request itself, POST /oauth/token, answers errors with 400 and a JSON object with error and error_description:

A token request with a JSON body instead of form data gets 405 Method Not Allowed, with a JSON problem object as its body. Authentication shows the requests that work.

Wrong Address, Method or Content Type

• 404 Not Found, empty body. The path is not an endpoint. Check the spelling and the service URL: when DS Server runs as an application below an IIS site, the service URL includes the name of the application. The changelog of version 3.3.0, for example, names the printer endpoint document/printers, which answers 404; the endpoint is document/installedprinters.
• 405 Method Not Allowed, empty body. The path exists for another HTTP method. The Allow header names it, such as Allow: POST for a GET request to document/convert.
• 415 Unsupported Media Type. A request with a body was sent without the header Content-Type: application/json, or with another content type such as text/plain. The body is a JSON object with "title": "Unsupported Media Type" and "status": 415.

Handle Errors in .NET

The package TXTextControl.DocumentServices.DocumentProcessing turns a refused request into a ServiceRequestException. Its StatusCode property holds the HTTP status as an HttpStatusCode, and its message contains the method, the endpoint and the answer of DS Server:

POST request to document/convert failed: DS Server is not registered. (Status code 400 / BadRequest)
POST request to document/convert failed for unknown reasons. Status code 401 / Unauthorized.

The constructor of DocumentProcessing requests the access token right away. When that fails, because the credentials are wrong, the profile doesn't allow the grant type or DS Server can't be reached, the constructor throws an AggregateException whose inner exception says why, such as:

OAuth access token request failed. error: "invalid_client", error_description: "Invalid client secret."

The following console application handles each case:

using System.Net;
using TXTextControl.DocumentServices.DocumentProcessing;
using TXTextControl.DocumentServices.DocumentProcessing.OAuth;

var oauthSettings = new OAuthSettings("<client ID>", "<client secret>");
byte[] document = File.ReadAllBytes("document.docx");

try
{
    // The constructor requests the access token
    var documentProcessing = new DocumentProcessing("http://localhost:5000", oauthSettings);

    byte[] pdf = await documentProcessing.Convert(document, ReturnFormat.PDF);
    File.WriteAllBytes("document.pdf", pdf);
}
catch (ServiceRequestException exception) when (exception.StatusCode == HttpStatusCode.Unauthorized)
{
    Console.WriteLine("The access token was refused.");
}
catch (ServiceRequestException exception)
{
    // For example 400: "DS Server is not registered."
    Console.WriteLine($"{(int)exception.StatusCode}: {exception.Message}");
}
catch (AggregateException exception)
{
    // No access token: wrong credentials, grant type not allowed or server not reachable
    Console.WriteLine(exception.InnerException?.Message);
}

The code works as follows:

• The first catch block handles a refused token, the second every other status code of the Web API, with the message of DS Server.
• The third catch block handles a failed token request of the constructor. Its inner exception holds the OAuth error, or the connection error when the service URL is wrong.

InstalledPrinters is the exception: in version 5.0.0 of the package, it throws a plain Exception whose message starts with "ServiceRequestException when trying to parse response content of endpoint", followed by the message of the refused request, and which has no status code.

In version 5.0.0 of the package, an instance created with DocumentProcessing.CreateInstanceAsync requests a token but doesn't send it with its requests. With OAuth enabled, every call of such an instance fails with 401. Create the instance with the constructor, as the code above does.

Related Pages

• Authentication: request and send access tokens.
• Licensing: register DS Server with a serial number.
• Enable OAuth: switch the token check on or off.
• DocumentProcessing: the endpoints and the errors each one lists.