GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
Guides
Start typing to search…

Product Importer Examples

Examples for the batch endpoint

Below you will find request and response examples for each Http response status as well as suggested actions.

202

Request

{
	"entries":[
		{
			"batchId":0,
			"merchantId":"123",
			"method":"insert",
			"product":{
        "id":"id",
        "title":"myTitle",
        "description":"myDescription",
        "link":"https://www.advertiser.com/myProduct",
        "imageLink":"https://www.advertiser.com/300x200/myProduct",
        "brand":"",
        "googleProductCategory":null,
        "gtin":"123456789",
        "price":{
          "currency":"EUR",
          "value":"49.99"
        },
        "availability":"in stock"
      },
      "feedId":"string"
    }
  ]
}

Response

{
  "operationToken" : "eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyMywib3BlcmF0aW9uSWQiOiIxNzE2YzExNC1mZThjLTRiZmYtOGFiNC0zYzM5YTQwY2M1ZGMiLCJleHAiOjE2MTYxNDIwMDJ9."
}

400

Request

{
  "entries" : [ ]
}

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-ab24-e9383cbc939e",
      "type" : "validation",
      "code" : "batch-empty",
      "instance" : "/preview/catalog/products/batch",
      "title" : "A batch request was rejected due to one or more errors.",
      "detail" : "The batch is empty."
    }
  ],
    "warnings" : [ ]
}

Action
Given the error's detail, fix your request and then re submit.

400

Request

{
  "entries" : [
    {
      "batchId" : "123"
    }
  ]
}

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-9f5b-49143a5bb0b6",
      "type" : "validation",
      "code" : "required-field",
      "instance" : "/preview/catalog/products/batch",
      "title" : "A batch request was rejected due to one or more errors.",
      "detail" : "entries.catalogId: field is required"
    },
    {
      "traceId" : "00000000-0000-0000-9f5b-49143a5bb0b6",
      "type" : "validation",
      "code" : "required-field",
      "instance" : "/preview/catalog/products/batch",
      "title" : "A batch request was rejected due to one or more errors.",
      "detail" : "entries.method: field is required"
    }
  ],
    "warnings" : [ ]
}

Action
Given the error's detail, fix your request and then re submit.

401

Request
Assuming the user post this payload along with an invalid bearer token

{
  "entries":[
    {
      "batchId":0,
      "merchantId":"123",
      "method":"insert",
      "product":{
        "id":"id",
        "title":"myTitle",
        "description":"myDescription",
        "link":"https://www.advertiser.com/myProduct",
        "imageLink":"https://www.advertiser.com/300x200/myProduct",
        "brand":"",
        "googleProductCategory":null,
        "gtin":"123456789",
        "price":{
          "currency":"EUR",
          "value":"49.99"
        },
        "availability":"in stock"
      },
      "feedId":"string"
    }
  ]
}

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-f2a6-b916ca584348",
      "type" : "authentication",
      "code" : "not-authenticated",
      "instance" : "/preview/catalog/products/batch",
      "title" : "User is not authenticated",
      "detail" : ""
    }
  ],
  "warnings" : [ ]
}

Action
Request a new token from the authentication endpoint and then retry.

403

Request
Assuming the current authenticated user doesn't have the permission to manage merchant (aka partner) 123

{
  "entries":[
    {
      "batchId":0,
      "merchantId":"123",
      "method":"insert",
      "product":{
        "id":"id",
        "title":"myTitle",
        "description":"myDescription",
        "link":"https://www.advertiser.com/myProduct",
        "imageLink":"https://www.advertiser.com/300x200/myProduct",
        "brand":"",
        "googleProductCategory":null,
        "gtin":"123456789",
        "price":{
          "currency":"EUR",
          "value":"49.99"
        },
        "availability":"in stock"
      },
      "feedId":"string"
    }
  ]
}

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-89ce-d053d749483c",
      "type" : "authorization",
      "code" : "not-authorized",
      "instance" : "/preview/catalog/products/batch",
      "title" : "User is not authorized",
      "detail" : ""
    }
  ],
  "warnings" : [ ]
}

Action
Check the credentials you used to authenticate, check the merchantId you used, fix and the retry.

404

Doesn't apply to this particular route.

413

Request

{
  "entries":[
    {
      "batchId":0,
      "merchantId":"123",
      "method":"insert",
      "product":{
        "id":"id",
        "title":"myTitle",
        "description":"myDescription",
        "link":"https://www.advertiser.com/myProduct",
        "imageLink":"https://www.advertiser.com/300x200/myProduct",
        "brand":"",
        "googleProductCategory":null,
        "gtin":"123456789",
        "price":{
          "currency":"EUR",
          "value":"49.99"
        },
        "availability":"in stock"
      },
      "feedId":"string"
    },
    {...}
     ]
    }

Response
No body.
Action
Reduce size of text field if any is over the field capacity or reduce the size of the batch, and then retry.

429

Request

{
  "entries":[
    {
      "batchId":0,
      "merchantId":"123",
      "method":"insert",
      "product":{
        "id":"id",
        "title":"myTitle",
        "description":"myDescription",
        "link":"https://www.advertiser.com/myProduct",
        "imageLink":"https://www.advertiser.com/300x200/myProduct",
        "brand":"",
        "googleProductCategory":null,
        "gtin":"123456789",
        "price":{
          "currency":"EUR",
          "value":"49.99"
        },
        "availability":"in stock"
      },
      "feedId":"string"
    }
  ]
}

Response

{
"errors" : [
{
"traceId" : "00000000-0000-0000-f7d4-2d7504f11523",
"type" : "availability",
"code" : "too-many-requests",
"instance" : "/preview/catalog/products/batch",
"title" : "Too many requests. Retry in 5 seconds",
"detail" : ""
}
],
"warnings" : [ ]
}

Action
Wait for the time provided before retrying using an exponential backoff algorithm.
Consider checking the number of products you're trying to send. The default limit is set to 3000 products / s per merchant.

500

Request

{
  "entries":[
    {
      "batchId":0,
      "merchantId":"123",
      "method":"insert",
      "product":{
        "id":"id",
        "title":"myTitle",
        "description":"myDescription",
        "link":"https://www.advertiser.com/myProduct",
        "imageLink":"https://www.advertiser.com/300x200/myProduct",
        "brand":"",
        "googleProductCategory":null,
        "gtin":"123456789",
        "price":{
          "currency":"EUR",
          "value":"49.99"
        },
        "availability":"in stock"
      },
      "feedId":"string"
    }
  ]
}

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-4ab7-8451b807408e",
      "type" : "availability",
      "code" : "internal-error",
      "instance" : "/preview/catalog/products/batch",
      "title" : "Internal Server Error",
      "detail" : ""
    }
  ],
  "warnings" : [ ]
}

Action
Retry using a exponential backoff algorithm.

503

Request

{
  "entries":[
    {
      "batchId":0,
      "merchantId":"123",
      "method":"insert",
      "product":{
        "id":"id",
        "title":"myTitle",
        "description":"myDescription",
        "link":"https://www.advertiser.com/myProduct",
        "imageLink":"https://www.advertiser.com/300x200/myProduct",
        "brand":"",
        "googleProductCategory":null,
        "gtin":"123456789",
        "price":{
          "currency":"EUR",
          "value":"49.99"
        },
        "availability":"in stock"
      },
      "feedId":"string"
    }
  ]
}

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-359a-9ad153aa43dd",
      "type" : "availability",
      "code" : "service-unavailable",
      "instance" : "/preview/catalog/products/batch",
      "title" : "Service unavailable.",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
Retry using a exponential backoff algorithm.

Examples for the report endpoint

200

Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6IjQyOTUyMzFmLWVmYTMtNDQzMy05NjA4LWI0ZDdkZTJjOThiNyIsImV4cCI6MTYxNjE0NTEzNX0.

Response

{
  "status" : "ACCEPTED",
  "importRequestTimestamp" : "1615799535383",
  "numberOfProductsInTheBatch" : "1",
  "numberOfProductsUpserted" : "0",
  "numberOfProductsDeleted" : "0",
  "numberOfProductsWithErrors" : "0",
  "errorDetails" : [ ]
}

Action
The batch has been accepted, its treatment hasn't started yet.

200

Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6IjQyOTUyMzFmLWVmYTMtNDQzMy05NjA4LWI0ZDdkZTJjOThiNyIsImV4cCI6MTYxNjE0NTEzNX0.

Response

{
  "status" : "VALIDATED",
  "importRequestTimestamp" : "1615799535032",
  "numberOfProductsInTheBatch" : "2",
  "numberOfProductsUpserted" : "2",
  "numberOfProductsDeleted" : "0",
  "numberOfProductsWithErrors" : "0",
  "errorDetails" : [ ]
}

Action
The batch has been fully validated without any error.

200

Request

  • Assuming a batch of one product has been submitted succesfully
  • Assuming a transformation happens on the imageUrl such as text is prepended to the originalImage Url leading to some possible overflow.
HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6IjQyOTUyMzFmLWVmYTMtNDQzMy05NjA4LWI0ZDdkZTJjOThiNyIsImV4cCI6MTYxNjE0NTEzNX0.

Response

{
  "status":"FAILED",
  "importRequestTimestamp":"1615818496157",
  "numberOfProductsInTheBatch":"1",
  "numberOfProductsUpserted":"0",
  "numberOfProductsDeleted":"0",
  "numberOfProductsWithErrors":"1",
  "errorDetails":[
    {
      "productId":"test-v3-1615818478409",
      "errors":[
        {
          "type":"OverlargeBigImage",
          "message":"{\"Length\":1042}",
          "isServerRelated":false
        }
      ]
    }
  ]
}

Action
Because Criteo apply some transformation to adapt the incoming format to Criteo product definition, it may happen that Criteo fails to transform a product.
Such issues can be fixed by either changing the product definition or the transformation procedure.

400

Request

HTTP GET /preview/catalog/products/batch/report/invalidToken

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-1032-0fa670f40edf",
      "type" : "validation",
      "code" : "catalog-operation-token-is-malformed",
      "instance" : "/preview/catalog/products/batch/report/invalidToken",
      "title" : "The operationToken is malformed.",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
Fix then retry.

403

Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-6864-75f39046f226",
      "type" : "authorization",
      "code" : "not-authorized",
      "instance" : "/preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEsIm9wZXJhdGlvbklkIjoib3BlcmF0aW9uX2lkX3Rlc3QiLCJleHAiOjE2MTYwNjEwMTN9.",
      "title" : "User is not authorized",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
Check the credentials you used to access this operation is authorized to access this partner's operation.

404

Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-6d24-98c37d815352",
      "type" : "validation",
      "code" : "catalog-operation-not-found",
      "instance" : "/preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
      "title" : "Operation 'c669bfc5-631a-4172-988b-3497ed8798ff' not found.",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
This operation hasn't been found. This could happen in case of a severe unavailability.
Criteo recommends to resubmit the entire batch.

413

Request
Any corrupted token such as the payload is really too heavy.
Response
No body.
Action
Fix.

429

Request
Assuming you're sending too many requests and hit your limit.
Criteo throttles your requests.

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-f7d4-2d7504f11524",
      "type" : "availability",
      "code" : "too-many-requests",
      "instance" : "/preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
      "title" : "Too many requests. Retry in 5 seconds",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
Wait for the time provided before retrying using an exponential backoff algorithm.
As the average time to get a report of 1000 products should be less than 3 seconds, Criteo recommends to start polling after 3 seconds and then retry using the exponential backoff algorithm.

500

Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-4ab7-8451b807408e",
      "type" : "availability",
      "code" : "internal-error",
      "instance" : "/preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
      "title" : "Internal Server Error",
      "detail" : ""
    }
  ],
  "warnings" : [ ]
}

Action
Retry using a exponential backoff algorithm.

503

Request

HTTP GET /preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.

Response

{
  "errors" : [
    {
      "traceId" : "00000000-0000-0000-359a-9ad153aa43dd",
      "type" : "availability",
      "code" : "service-unavailable",
      "instance" : "/preview/catalog/products/batch/report/eyJhbGciOiJub25lIn0.eyJwYXJ0bmVySWQiOjEyLCJvcGVyYXRpb25JZCI6ImM2NjliZmM1LTYzMWEtNDE3Mi05ODhiLTM0OTdlZDg3OThmZiIsImV4cCI6MTYxNjE0NTEzNX0.",
      "title" : "Service unavailable.",
      "detail" : ""
    }
  ],
    "warnings" : [ ]
}

Action
Retry using a exponential backoff algorithm.

Updated about 6 hours ago

Documentation

Support

Company

© Criteo 2025. All rights reserved.