Errors

When a request fails, the API answers with a 4xx or 5xx status and a JSON body called ErrorResult. The shape is the same for every endpoint.

The error bodyCopy Anchor Link

Deleting a document that other records still depend on:

curl -X DELETE https://<your-instance>/api/documents/orders/internet/8841 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "messages": ["Document cannot be deleted"],
  "exception": "Document cannot be deleted",
  "errorId": "5f0c2a4e-6f43-4c0b-9a55-0d5b8f1f3c21",
  "supportMessage": "Provide the ErrorId 5f0c2a4e-6f43-4c0b-9a55-0d5b8f1f3c21 to the support team for further analysis.",
  "statusCode": 400
}

As everywhere in the API, a field without a value is left out.

Validation errors list everything at onceCopy Anchor Link

The server validates the whole request before it writes anything. If you create an order without a customer and without a warehouse, you get both problems in one response:

{
  "messages": ["CustomerId is required for new order.", "WarehouseId is required for new order."],
  "statusCode": 400
}

(Shortened; the other fields are present as above.)

code and paramsCopy Anchor Link

Most errors carry only messages. A failure gets a code when a client is expected to react to that specific situation in its own way, for example by showing its own translated text. params then holds the values to put into that text.

• If code is present, branch on it. Do not parse messages.
• If code is absent, show your own generic error message and log messages and errorId.

When a coded validation failure covers several violations, the body also has an errors array with one code, message and params per violation.

Status codesCopy Anchor Link

Handling errors in codeCopy Anchor Link

using System.Net.Http.Json;

var response = await http.DeleteAsync("/api/documents/orders/internet/8841");

if (!response.IsSuccessStatusCode)
{
    var error = await response.Content.ReadFromJsonAsync<ErrorResult>();

    if (error?.Code is not null)
    {
        // a failure you are expected to handle: branch on error.Code
    }

    throw new InvalidOperationException(
        $"WinShop API {(int)response.StatusCode}: {string.Join("; ", error?.Messages ?? [])} (errorId {error?.ErrorId})");
}

record ErrorResult(
    List<string> Messages,
    string? Exception,
    string? Source,
    string? ErrorId,
    string? SupportMessage,
    int StatusCode,
    string? Code,
    Dictionary<string, string>? Params);

Reporting a problemCopy Anchor Link

Write to [email protected] and include:

• the errorId from the response,
• the instance address, the HTTP method and the path,
• the time of the request.

With the errorId, support can find the exact failure in the server log.