> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling parcel errors

<Warning>
  This page applies to v2 of the Sendcloud API and is no longer maintained. To learn more about switching to API v3,
  read our [migration guide](/docs/getting-started/migration-guidelines-for-api-v3#parcels/shipments).
</Warning>

In the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint, when a request contains errors, the API responds with an error message and no parcels in the request are processed. This is the default behavior for this endpoint.

```json Example of a validation error message response theme={null}
{
  "error": {
    "code": 400,
    "request": "api/v2/parcels",
    "message": "house_number: 'This field cannot be blank.'"
  }
}
```

## Getting more detailed error information

To get more detailed information about errors that occur during parcel creation, pass the `errors` query parameter to your request. It can be one of `errors=verbose` or `errors=verbose-carrier`.

```http Request method and URL, with errors query parameter theme={null}
POST https://panel.sendcloud.sc/api/v2/parcels?errors=verbose
```

The response structure will change when using the `errors` query parameter:

```json Example response structure with the errors query parameter theme={null}
{
  "parcels": [], // List of successfully created parcels
  "failed_parcels": [] // List of parcels that failed
}
```

The behavior of the endpoint also changes when the `errors` query parameter is used. All parcels in the `parcels` key will be processed, while the parcels in the `failed_parcels` key will not be processed. This differs from the default behavior, where if any parcel in the request contains an error, the entire request fails.

### `errors=verbose`

Including the query parameter `errors=verbose` returns **errors that occurred during the validation of the request**. These errors only pertain to the provided data in the request (e.g. an invalid country was provided).

```json Example response using errors=verbose theme={null}
{
  "parcels": [],
  "failed_parcels": [
    {
      "parcel": {
        //... parcel data that was sent in the request
      },
      "errors": {
        "name": ["This field is required."]
      }
    }
  ]
}
```

### `errors=verbose-carrier`

Including the query parameter `errors=verbose-carrier` returns **errors that occurred on the carrier's side**. It is impossible to predict if these errors will happen ahead of time. It makes sense to use this query parameter if `request_label_async` is set to `false` and `request_label` is set to `true`. In such cases, errors can be recognized by the following structure:

```json Example response using errors=verbose-carrier theme={null}
{
  "parcels": [],
  "failed_parcels": [
    {
      "parcel": {
        //... parcel data that was sent in the request
      },
      "errors": {
        "non_field_errors": ["Service error: <text of the message from the carrier>"]
      }
    }
  ]
}
```

#### HTTP response codes when using the `errors=verbose-carrier` query parameter

When creating parcels, the behaviour of errors=verbose-carrier depends on the request data. The following scenarios apply:

Sending one parcel:

* If the parcel is sent successfully, the API will return an `HTTP 200` status code and the serialized parcel in the response body.
* If the parcel fails to send, the API will return an `HTTP 400` status code and a carrier error message.

Sending multiple parcels (including multi-collo):

* If all parcels are sent successfully, the API will return an `HTTP 200` status code and the serialized parcels in the response.
* If some parcels fail to send, the API will return an `HTTP 200` status code and a `failed_parcels` field in the response. The `failed_parcels` field is a list of dictionaries, where each dictionary contains the parcel data and the errors that occurred for that parcel.
* If all parcels fail to send, the API will return an `HTTP 400` status code along with the errors listed in the same way as in the previous scenario.