# Bulk Service Response

> The Bulk API submit response: accepted and rejected items, result IDs, batch counts, outcome arrays, sample responses and errors.

Source: https://docs.easyparser.com/bulk-integration/bulk-service-response

When you submit a [Bulk Service Request](/bulk-integration/bulk-service-request), the response tells you which input values were accepted and which were rejected, and why. It does not contain the parsed Amazon data: each accepted value gets a result `id` that you use to fetch the data from the [Data Service](/bulk-integration/data-service-request).

## Response structure

```
success
message                      only when the whole request fails
meta_data
  bulk_request_id
  total_count
  accepted_count
  invalid_count
  insufficient_credit_count
  failed_count
  rate_limit_exceeded_count
data
  accepted[]                 one object per accepted group
    platform, operation, domain, callback_url, group_id
    ship_to
      zipCode[]
    results[]                one entry per input value
      id, credit, asin | keyword | seller_id | url | link | identifier | ...
  invalid[]
  failed[]
  insufficient_credit[]
  rate_limit_exceeded[]
```

## Response fields

### Top-level fields

| Field | Type | Description |
|---|---|---|
| `success` | boolean | `true` when the request was processed, even if only some items were accepted. `false` only when the whole request is malformed. |
| `message` | string | Short error description, present only when the request fails. Example: `Bad request.` |
| `meta_data` | object | Counts for the whole request. |
| `data` | object | Items grouped by outcome. |

### `meta_data`

Each count equals the number of items in the array of the same name in `data` (for example, `invalid_count` is the number of items in `data.invalid`).

| Field | Type | Description |
|---|---|---|
| `bulk_request_id` | string | ID of this whole submission. Use it to find the request on the [Bulk Requests](https://app.easyparser.com/bulk-requests) page of the web app. |
| `total_count` | integer | Number of input values in the request. |
| `accepted_count` | integer | Values accepted and queued for processing. |
| `invalid_count` | integer | Values rejected by validation. |
| `insufficient_credit_count` | integer | Values not accepted because your credits ran out. |
| `failed_count` | integer | Values that hit a server-side failure. |
| `rate_limit_exceeded_count` | integer | Values not accepted because the per-minute limit was reached. |

### `data`

Each item appears in exactly one array. Empty arrays may be left out of the response.

| Field | Type | Description |
|---|---|---|
| `accepted` | array | Accepted groups with their result IDs. |
| `invalid` | array | Items rejected by validation. |
| `failed` | array | Items that hit a server-side failure. |
| `insufficient_credit` | array | Items dropped because your credits ran out. |
| `rate_limit_exceeded` | array | Items dropped because the per-minute limit was reached. |

Every item carries a `group_id` that identifies the request object it came from, whichever array it ends up in.

### `data.accepted[]`

Each object echoes one accepted group from your request and lists its queries under `results`.

| Field | Type | Description |
|---|---|---|
| `platform` | string | Platform of the group, for example `AMZ`. |
| `operation` | string | Operation of the group, for example `DETAIL`. |
| `domain` | string | Marketplace of the group, for example `.com`. |
| `callback_url` | string | URL that receives the webhook for each finished query. The webhook does not carry the parsed data. |
| `ship_to` | object | Delivery location used for the group. Without `address_id`, the marketplace default is used. |
| `ship_to.zipCode` | array | Zip code or codes used to localize the requests. |
| `group_id` | string | ID of this group. Each object in your request array becomes one group. |
| `results` | array | One entry per input value, each with its own result `id`. |

### `results[]`

Each entry is one query. `id` and `credit` are always present; the other fields depend on the operation and the input key you sent.

| Field | Type | Description |
|---|---|---|
| `id` | string | Result ID. Use it to fetch the result from the Data Service. |
| `credit` | integer | Credits charged for this query, using the same rules as the Real-Time API. Example: `6` for `SIMILAR_PRODUCTS` with `similar_limit` `50`. |
| `asin` | string | Submitted ASIN. For ASIN input (`DETAIL`, `OFFER`, `SIMILAR_PRODUCTS` and other ASIN operations). |
| `keyword` | string | Submitted search term. For `SEARCH` with `keywords`. |
| `seller_id` | string | Submitted seller ID. For `SELLER_PROFILE`, `SELLER_PRODUCTS`, `SELLER_FEEDBACK` with `seller_ids`. |
| `url` | string | Submitted full URL. For URL input. Seller URLs use the `/sp?seller=` form (`SELLER_PROFILE`, `SELLER_FEEDBACK`) or the `/s?me=` form (`SELLER_PRODUCTS`). |
| `link` | string | Relative path of the submitted URL. For URL input, except `SELLER_FEEDBACK`, which returns only `url`. |
| `identifier` | string | Submitted product code. For `PRODUCT_LOOKUP`. |
| `identifier_type` | string | Code type used for the lookup, for example `UPC`. For `PRODUCT_LOOKUP`. |
| `min_rating` | integer | Echo of the minimum rating filter. For `SELLER_FEEDBACK`. When you do not send a filter, none is applied and the echoed value may be `0`. |
| `max_rating` | integer | Echo of the maximum rating filter. For `SELLER_FEEDBACK`. When you do not send a filter, none is applied and the echoed value may be `0`. |
| `similar_limit` | integer | Echo of `similar_limit`. For `SIMILAR_PRODUCTS`. |

> **INFO:** Three IDs trace a bulk request: `meta_data.bulk_request_id` identifies the whole submission, `group_id` identifies one object from your request array, and `results[].id` identifies one query. Only `results[].id` works with the Data Service.

### `data.invalid[]`

Each object describes a validation error in the request.

| Field | Type | Description |
|---|---|---|
| `value` | string | Submitted value that caused the rejection. |
| `message` | string | Reason for the rejection, including the value and its index. Example: `Invalid seller_id format at index 0: "AAK72K4OIWDXL827362"`. |
| `path` | string | General location of the error, for example `body`. |
| `instancePath` | string | Path to the invalid field in the request, for example `/0/payload/seller_ids/0`. |
| `platform` | string | Platform of the rejected group. |
| `operation` | string | Operation of the rejected group. |
| `domain` | string | Marketplace of the rejected group. |
| `payload_count` | integer | Number of input values in the rejected group's payload. |
| `group_id` | string | ID of the group the item belongs to. |

### `data.failed[]`

Each object is an item that passed validation but hit a server-side failure. The original request fields are echoed so you can identify and resend the item.

| Field | Type | Description |
|---|---|---|
| `id` | string | ID assigned to the failed item. |
| `platform` | string | Platform of the item. |
| `operation` | string | Operation of the item. |
| `domain` | string | Marketplace of the item. |
| `payload` | object | The single input value, for example `{ "asin": "0000306037" }`. |
| `callback_url` | string | Callback URL sent with the request. |
| `group_id` | string | ID of the group the item belongs to. |

### `data.rate_limit_exceeded[]`

Each object is an item dropped because your plan's Bulk API per-minute limit was reached. The rest of the request is still processed.

| Field | Type | Description |
|---|---|---|
| `message` | string | Error message: `[!] Minute request limit exceeded.` |
| `payload` | object | The dropped item, with its assigned `id` and `credit`. |
| `payload.platform` | string | Platform of the item. |
| `payload.operation` | string | Operation of the item. |
| `payload.domain` | string | Marketplace of the item. |
| `payload.payload` | object | The single input value, for example `{ "asin": "B000PXYADK" }`. |
| `payload.callback_url` | string | Callback URL sent with the request. |
| `payload.id` | string | ID assigned to the dropped item. |
| `payload.credit` | integer | Nominal credit cost of the item. Not charged. |
| `group_id` | string | ID of the group the item belongs to. |

### `data.insufficient_credit[]`

Items are accepted in order until your credits run out. Each remaining item is returned here with the same structure as `data.rate_limit_exceeded[]`.

| Field | Type | Description |
|---|---|---|
| `message` | string | Error message: `[!] You do not have enough credit to perform this action.` |
| `payload` | object | The dropped item, with `platform`, `operation`, `domain`, `payload`, `callback_url`, `id` and `credit` as in `data.rate_limit_exceeded[]`. |
| `group_id` | string | ID of the group the item belongs to. |

## Status values

Each input value is evaluated on its own, so one request can have several outcomes. `success` stays `true` in that case, and the `meta_data` counts show the split. Check the arrays rather than `success` alone.

| Outcome | Array | Charged | What to do |
|---|---|---|---|
| Accepted | `data.accepted` | Yes, the `credit` of each result | Store each `results[].id` and fetch the result from the Data Service. |
| Invalid | `data.invalid` | No | Fix the value at `instancePath` and send it again. |
| Failed | `data.failed` | No | Send the item again in a new request. |
| Insufficient credit | `data.insufficient_credit` | No | Add credits or wait for your credits to reset, then send the items again. |
| Rate limit exceeded | `data.rate_limit_exceeded` | No | Send the items again after the current minute. |

> **INFO:** Credits are charged only for items in `data.accepted`. A `credit` value on a dropped item shows its nominal cost, not a charge.

An accepted query is processed in the background and ends with status `success` or `failure`. Easyparser then sends a webhook to the group's `callback_url`. See [Data Service Response](/bulk-integration/data-service-response) for the query record and its statuses. Results are kept for at most 24 hours.

## Sample responses

#### Sample response: all items accepted (DETAIL, .com)

```json
{
  "success": true,
  "meta_data": {
    "bulk_request_id": "01a0341d-c6a8-722b-9189-2f2ee09608ef",
    "total_count": 3,
    "accepted_count": 3,
    "invalid_count": 0,
    "insufficient_credit_count": 0,
    "failed_count": 0,
    "rate_limit_exceeded_count": 0
  },
  "data": {
    "accepted": [
      {
        "platform": "AMZ",
        "operation": "DETAIL",
        "domain": ".com",
        "callback_url": "https://example.com/webhook",
        "ship_to": { "zipCode": ["19805"] },
        "group_id": "01a0341d-c6be-7ccb-b916-49e17627b560",
        "results": [
          { "asin": "B00004RFMB", "id": "qwe78933-7614-40b3-9a40-def192b74810", "credit": 1 },
          { "asin": "B00004RFMC", "id": "xyz5677e-c8a7-47e1-91a1-966bc448e0e8", "credit": 1 },
          { "asin": "B00004RFMJ", "id": "abc123b5-c346-4909-aa6b-f4194318dc3a", "credit": 1 }
        ]
      }
    ],
    "invalid": [],
    "failed": [],
    "insufficient_credit": [],
    "rate_limit_exceeded": []
  }
}
```

#### Sample response: invalid item (wrong seller_id)

```json
{
  "success": true,
  "meta_data": {
    "bulk_request_id": "01a038b0-742b-73c3-a3f1-7666d2c4aeb6",
    "total_count": 2,
    "accepted_count": 1,
    "invalid_count": 1,
    "insufficient_credit_count": 0,
    "failed_count": 0,
    "rate_limit_exceeded_count": 0
  },
  "data": {
    "accepted": [
      {
        "platform": "AMZ",
        "operation": "DETAIL",
        "domain": ".com",
        "callback_url": "https://example.com/webhook",
        "ship_to": { "zipCode": ["19805"] },
        "group_id": "01a038b0-7517-7e9c-b5eb-c56cd50ad8bf",
        "results": [
          { "asin": "B00063NUW6", "id": "01a038b0-7516-7fb0-8cb5-b1d98e49a982", "credit": 1 }
        ]
      }
    ],
    "invalid": [
      {
        "value": "AAK72K4OIWDXL827362",
        "message": "Invalid seller_id format at index 0: \"AAK72K4OIWDXL827362\"",
        "path": "body",
        "instancePath": "/0/payload/seller_ids/0",
        "platform": "AMZ",
        "operation": "SELLER_PROFILE",
        "domain": ".com",
        "payload_count": 1,
        "group_id": "01a038b0-7517-7e9c-b5eb-c56dc887a371"
      }
    ],
    "failed": [],
    "insufficient_credit": [],
    "rate_limit_exceeded": []
  }
}
```

#### Sample response: failed items

```json
{
  "success": true,
  "meta_data": {
    "bulk_request_id": "01a03e32-cbf1-7406-a423-462adab9ed87",
    "total_count": 8,
    "accepted_count": 4,
    "invalid_count": 0,
    "insufficient_credit_count": 0,
    "failed_count": 4,
    "rate_limit_exceeded_count": 0
  },
  "data": {
    "accepted": [
      {
        "group_id": "01a03e32-cbf9-71e4-af94-c8d2abdfe02b",
        "platform": "AMZ",
        "operation": "DETAIL",
        "domain": ".com",
        "callback_url": "https://example.com/webhook",
        "ship_to": { "zipCode": ["19805"] },
        "results": [
          { "asin": "0002158639", "id": "019ef8e0-5403-72f3-86dc-110ad7fed88c", "credit": 1 }
        ]
      }
    ],
    "invalid": [],
    "failed": [
      {
        "group_id": "01a03e32-cbf9-71e4-af94-c8d1fda44b9b",
        "id": "019ef8e0-5402-7e64-9a7f-f6e8b20be5fe",
        "platform": "AMZ",
        "operation": "DETAIL",
        "payload": { "asin": "0000306037" },
        "domain": ".com",
        "callback_url": "https://example.com/webhook"
      }
    ],
    "insufficient_credit": [],
    "rate_limit_exceeded": []
  }
}
```

#### Sample response: rate-limited items (105 sent, 100 accepted, 5 rate-limited)

```json
{
  "success": true,
  "meta_data": {
    "bulk_request_id": "01a03e32-cbf1-7406-a423-462adab9ed65",
    "total_count": 105,
    "accepted_count": 100,
    "invalid_count": 0,
    "insufficient_credit_count": 0,
    "failed_count": 0,
    "rate_limit_exceeded_count": 5
  },
  "data": {
    "accepted": [
      {
        "group_id": "01a03e32-cbf9-71e4-af94-c8d1fda44a3c",
        "platform": "AMZ",
        "operation": "DETAIL",
        "domain": ".com",
        "callback_url": "https://example.com/webhook",
        "ship_to": { "zipCode": ["19805"] },
        "results": [
          { "asin": "B000PW6WYQ", "id": "019ef4d9-e721-7b23-8ad4-d54c51b3cba2", "credit": 1 }
        ]
      }
    ],
    "invalid": [],
    "failed": [],
    "insufficient_credit": [],
    "rate_limit_exceeded": [
      {
        "group_id": "01a03e32-cbf9-71e4-af43-c8d1fda54b1e",
        "message": "[!] Minute request limit exceeded.",
        "payload": {
          "platform": "AMZ",
          "operation": "DETAIL",
          "domain": ".com",
          "payload": { "asin": "B000PXYADK" },
          "callback_url": "https://example.com/webhook",
          "id": "019ef4d9-e722-7a30-a866-dee242c5c0f1",
          "credit": 1
        }
      }
    ]
  }
}
```

#### Sample response: insufficient credit (80 sent, 74 accepted, 6 dropped)

```json
{
  "success": true,
  "meta_data": {
    "bulk_request_id": "01a03e32-cbf1-7406-a423-462bcab6ar23",
    "total_count": 80,
    "accepted_count": 74,
    "invalid_count": 0,
    "insufficient_credit_count": 6,
    "failed_count": 0,
    "rate_limit_exceeded_count": 0
  },
  "data": {
    "accepted": [
      {
        "group_id": "01a03e32-cbf9-71e4-af54-c7d1fda44a3k",
        "platform": "AMZ",
        "operation": "DETAIL",
        "domain": ".com",
        "callback_url": "https://example.com/webhook",
        "ship_to": { "zipCode": ["19805"] },
        "results": [
          { "asin": "B000PWTITM", "id": "019ef975-16bd-7242-9fd5-c6e031409f70", "credit": 1 }
        ]
      }
    ],
    "invalid": [],
    "failed": [],
    "insufficient_credit": [
      {
        "group_id": "01a03e32-cbf9-71e4-af94-c8d4alo98b4s",
        "message": "[!] You do not have enough credit to perform this action.",
        "payload": {
          "platform": "AMZ",
          "operation": "DETAIL",
          "domain": ".com",
          "payload": { "asin": "B000PWU23I" },
          "callback_url": "https://example.com/webhook",
          "id": "019ef975-16bd-7242-9fd5-c6e4f1d939f7",
          "credit": 1
        }
      }
    ],
    "rate_limit_exceeded": []
  }
}
```

#### Sample results[] entries by input type

```javascript
// ASIN input (DETAIL, OFFER)
{ "asin": "B00004RFMB", "id": "qwe78933-7614-40b3-9a40-def192b74810", "credit": 1 }

// Keyword input (SEARCH)
{ "keyword": "car", "id": "019eef7c-ee5c-7cde-945c-ecb0eeb4ead3", "credit": 1 }

// Seller ID input (SELLER_PROFILE, SELLER_PRODUCTS, SELLER_FEEDBACK)
{ "seller_id": "A29DXXRE3BKYH7", "id": "019ef42e-8f2d-7ca5-997a-bc87609f5085", "credit": 1 }

// URL input (SELLER_PROFILE): storefront /sp?...seller=
{ "url": "https://www.amazon.com/sp?ie=UTF8&seller=A29DXXRE3BKYH7", "link": "/sp?ie=UTF8&seller=A29DXXRE3BKYH7", "id": "019ef42a-dd1f-7fb4-a07f-af59318f979f", "credit": 1 }

// URL input (SELLER_PRODUCTS): storefront /s?me=
{ "url": "https://www.amazon.com/s?me=A29DXXRE3BKYH7", "link": "/s?me=A29DXXRE3BKYH7", "id": "019ef441-7ee2-722d-ad36-96fdf5296136", "credit": 1 }

// URL input (SELLER_FEEDBACK): storefront /sp?...seller=, returns url only, no link
{ "url": "https://www.amazon.com/sp?ie=UTF8&seller=A29DXXRE3BKYH7", "min_rating": 0, "max_rating": 0, "id": "019ef42d-060a-71d4-b3e1-82e65cf37579", "credit": 1 }

// PRODUCT_LOOKUP
{ "identifier": "724382975021", "identifier_type": "UPC", "id": "019ef43f-14f2-7a8c-b737-466f0ce0b54a", "credit": 1 }

// SIMILAR_PRODUCTS
{ "asin": "B0G2V8898X", "similar_limit": 50, "id": "01a1399a-cb8d-7361-90b0-2f370ece0155", "credit": 6 }
```

## Errors

Problems with single items do not fail the request; they appear in the outcome arrays above. The request as a whole fails only when it cannot be processed.

| Case | What you receive |
|---|---|
| Malformed request body | `success` is `false` and `message` describes the error, for example `Bad request.` |
| Missing `api-key` header | Error `MSG0035`: `Request header does not have api-key`. |
| Invalid API key | Error `MSG0023`: `Invalid API Key. Please verify your API key is valid`. |
| Value fails validation | Item in `data.invalid`, for example `Invalid seller_id format at index 0`. |
| Credits run out | Remaining items in `data.insufficient_credit`: `[!] You do not have enough credit to perform this action.` |
| Per-minute limit reached | Items above the limit in `data.rate_limit_exceeded`: `[!] Minute request limit exceeded.` |

## Related

- [Bulk Service Request](/bulk-integration/bulk-service-request)
- [Data Service Request](/bulk-integration/data-service-request)
- [Data Service Response](/bulk-integration/data-service-response)
- [Bulk API overview](/bulk-integration/overview)
- [Credit Consumption](/essentials/credit-consumption)