Skip to main content
In the 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.
Example of a validation error message response
{
  "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.
Request method and URL, with errors query parameter
POST https://panel.sendcloud.sc/api/v2/parcels?errors=verbose
The response structure will change when using the errors query parameter:
Example response structure with the errors query parameter
{
  "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).
Example response using errors=verbose
{
  "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:
Example response using errors=verbose-carrier
{
  "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.