HTTP Status Codes

When interacting with the UC Marketplace API, each request you make will return a response in JSON format — a widely used, human- and machine-readable format for transmitting data.

Along with this JSON body, an HTTP status code is provided to indicate the outcome of the request. These codes help you determine whether the request was successful or if there was an issue, and they often provide guidance on how to resolve problems when they arise.

✅ Successful Requests

Any HTTP status code starting with 2 (like 200 OK, 201 Created, or 204 No Content) means that your request was processed successfully.

Example: Retrieving a product by a product url key

Request (cURL)

curl -X GET https://ucmarketplace-api-gateway.com/V1/product?url-key=kids-table-and-chairs-set-study-desk   -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM"

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1448,
  "name": "Kids Table and Chairs Set - Study Desk",
  "url_key": "kids-table-and-chairs-set-study-desk",
  "sku": "Kids Table and Chairs Set - Study Desk",
  "type_id": "configurable",
  "in_stock": true,
  ...
}

ℹ️ Understanding Response Categories

The first digit of the HTTP status code helps you classify the type of response:

2xx – The request succeeded.
4xx – A client-side error occurred (usually an issue in your request).
5xx – A server-side error occurred (UC Marketplace's infrastructure or service).

❌ Common Error Examples

401 Unauthorized

This status appears when the request lacks valid authentication credentials, such as when using an incorrect API key.

Request

curl -X GET https://ucmarketplace-api-gateway.com/v1/storeview/default/user/quote/total-summary   -H "Authorization: Bearer test_invalid_key"

Response

HTTP/1.1 401 Unauthorized
Content-Type: application/hal+json

404 Not Found

This code is returned when the item you’re trying to access doesn’t exist.

Request

curl -X GET https://ucmarketplace-api-gateway.com/v1/storeview/default/user/total-summary   -H "Authorization: Bearer test_valid_key"

Response

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "message": "Request does not match any route."
}

📋 List of HTTP Status Codes Used by the API

Code	Meaning
200	OK – The operation was successful.
201	Created – A new resource has been created.
204	No Content – The resource was successfully removed or canceled.
400	Bad Request – There’s a problem with your request syntax or structure.
401	Unauthorized – Authentication failed; check your API key. This status code can be returned in case of missing or invalid token.
403	Forbidden – You're not allowed to access the resource. This status code can be returned if provided token is valid but lacks permission for the requested resource.
404	Not Found – The requested item does not exist.
419	Session Expired – Token has expired or session has timed out.
422	Unprocessable Entity – There’s a problem with one of the fields in your request.
500	Internal Server Error – Something went wrong on UC Marketplace’s side.
502	Bad Gateway – Temporary issue; try again shortly.
503	Service Unavailable – Service is down or under maintenance.
504	Gateway Timeout – The server took too long to respond.