Request & Response Standards

In Lidia APIs, the request and response structure may vary depending on the API group and endpoint type being used. The required fields, parameters, and response model of each endpoint are explained in detail on the API Reference page. This section summarizes the common request and response approach used during integration.

Request Structure

API requests are sent through the relevant base URL and service path. In requests, the HTTP method, header information, body fields, and query/path parameters, if any, are prepared according to the endpoint documentation.

While Client ID and AppKey are used in the request body for PIM API requests, authorization information is sent through the Authorization header in Commerce Engine services.

Response Structure

Successful responses may return the operation result, a list of records, or the relevant entity detail. In listing endpoints, the total record count and pagination information may be included in the response.

In error cases, an error message, error code, or error details may be returned together with the HTTP status code.

Field	Description	Example Usage
Accept	Specifies the response format.	application/json
Content-Type	Specifies the request body format.	application/json or application/*+json
Authorization	Carries Bearer token information in Commerce Engine services.	Bearer {access_token}
Body Params	Contains the request fields expected by the endpoint.	clientId, appKey, pageIndex, pageSize

Sample PIM Request

curl --request POST \
  --url https://{pim-api-url}/api/v2/query/products \
  --header 'accept: application/json' \
  --header 'content-type: application/*+json' \
  --data '{
    "clientId": "{clientId}",
    "appKey": "{appKey}",
    "pageIndex": 0,
    "pageSize": 25
  }'

Sample Response Structure

{
  "type": "Success",
  "message": "Products fetched successfully.",
  "totalCount": 3363,
  "result": [
    {
      "id": 1001,
      "name": "Example Product"
    }
  ]
}

Response check: On the integration side, the HTTP status code should be checked first, and then the result fields in the response should be processed. In listing endpoints, the total record count, pagination, and result fields should be evaluated together.

HTTP Status Codes

HTTP status codes indicate whether an API request was successful and what action should be taken in case of an error. Endpoint-specific error messages may also be included on the API Reference pages.

Status Code	Meaning	When is it returned?
200 OK	Successful	The request was processed successfully and a response body was returned.
201 Created	Created	A new record or resource was created successfully.
204 No Content	No content	The operation was successful, but no response body was returned.
400 Bad Request	Bad request	Returned when the request body, parameter format, or data type is invalid.
401 Unauthorized	Authentication error	Returned when authentication information is missing, incorrect, or invalid.
403 Forbidden	Authorization error	Returned when the user is authenticated but does not have sufficient permission for the related operation.
404 Not Found	Not found	Returned when the requested resource, record, or endpoint cannot be found.
409 Conflict	Conflict	Returned when the request conflicts with the current state of the resource.
422 Unprocessable Entity	Business rule error	Returned when the request format is correct, but the operation cannot be performed due to a business rule.
429 Too Many Requests	Rate limit exceeded	Returned when the defined request limit is exceeded.
500 Internal Server Error	Server error	Returned when an unexpected server error occurs.