Logic4 API - Response format

Terug naar beginpagina

Introduction

This document describes the format of the body returned by Logic4 API endpoints. The response format has changed with the move to version 3 endpoints.

From V3.0

From V3.0 onwards, the response body of endpoints contains unformatted JSON with the following attributes:

• No added whitespace, including newlines or indentation.
• Fields with a value of null are omitted.
• Successful responses have no wrapper, returned data can be parsed directly.
  • Endpoints which may return multiple results return an empty list if there are no results.
• Unsuccessful responses (HTTP 400) are provided in the problem details format.

Note that some endpoints return no body on success.

This compact JSON reduces overhead, resulting in faster response times and decreased network usage.

Problem details

Endpoints from V3.0 onwards use RFC 9457 for unsuccessful repsonses. This standard describes various fields and values, the Logic4 API uses the following:

• type - identifies the problem type
• title - human-readable summary of the problem type
• status - equals the status code of the HTTP response
• detail - human-readable explanation specific to this occurrence of the problem
• operationId - custom field to identify the occurrence

Example response:

{
  "type": "tag:api.logic4.nl,2025-08-16:InvalidRequest",
  "title": "The request has invalid parameters",
  "status": 400,
  "detail": "Geen orderregels gevonden om uit te leveren voor OrderId 300234",
  "operationId": "5e151dcea819025c0a829b0cd98f220a",
}

type

The type field identifies the problem type. It is intended to be parsed by a computer to identify a specific error.

The Logic4 API uses a non-dereferenceable tag URI as specified by RFC 4151. The structure is: tag:authorityName,date:specific.

Change policy

The type URI is fixed for any given error and will not change within the same version of a specific endpoint. However, under some circumstances the specific error returned might change without notice according to the following policy:

• Error responses accompanied by HTTP 500 are considered bugs and may change type at any time. The reponse may also be changed to use a different HTTP code.
• The URI tag:api.logic4.nl:2025-08-16:InvalidRequest is a generic HTTP 400 response. It may at any time be changed into a different error type with a 4XX status code.
  • Any other HTTP 400 response type will not change without notice.
  • When a HTTP 4XX error with an unknown response type is parsed, it should be treated as if it was a 400 error with type URI tag:api.logic4.nl:2025-08-16:InvalidRequest.

title

The title field is a human-readable summary of the problem type, in English. Examples:

• "The request has invalid parameters."
• "The resource cannot be modified due to invalid state."
• "The administration is in maintenance mode."

status

The status field is always equal to the status code of the HTTP response.

detail

The detail field is a human-readable explanation specific to this occurrence of the problem, in Dutch. It may help to correct the problem, for instance specifying the Id or name of a product, order customer etc. Examples:

• "Geen orderregels gevonden om uit te leveren voor OrderId 300234."
• "Geen voorraad voor ProductId 41900 en SupplierId 1001481."
• "Database is niet beschikbaar, probeer later opnieuw."
• "De administratie is in maintenance mode, probeer later opnieuw."

operationId

The custom field operationId can be used by Logic4 to find the request in our logging system.

Legacy

Endpoints before V3.0 differ in the following ways:

• Successful responses use the Logic4Response or Logic4ResponseList wrappers.
  • Data should be parsed from the Value or Records fields depending on the wrapper used.
  • For successful responses, the ValidationMessages field is usually left empty but may contain warnings.
• Unsuccessful responses may use the same wrapper as successful responses, may return a raw string or may return a JSON object in the problem details format.
  • If the Logic4Response or Logic4ResponseList wrappers are used, error details are provided in the ValidationMessages field and the Value or Records fields are left empty.
• Some endpoints include fields with a value of null, others omit them by default.
• Formatted JSON is optionally supported.

Wrapper examples

Logic4Repsonse:

{
  "Value": 1,
  "ValidationMessages": []
}

Logic4ResponseList:

{
  "Records": [
    {
      "OrderId": 3
    }
  ],
  "RecordsCounter": 1,
  "ValidationMessages": []
}

Formatted JSON format

Legacy endpoints optionally support formatted JSON output containing:

• newlines
• indentation
• explicit null-values

To request the formatted JSON output, specify X-LOGIC4-FormattedJson in the request header (without a value). Note that this is not supported in V3.0+ endpoints.

We recommend against using this option because the output is larger, resulting in longer response times and increased network usage.