Error messages
Messages returned in customResponse.errorMessage, what causes them and what to do.
These messages come back in customResponse.errorMessage from Process shipments. The level tells you where to read the message: on the shipment, on one of its parcels, or on the batch as a whole.
We process a shipment as domestic when the recipient's countryIso is GB, and as international for every other destination. That decides whether the postcode and route checks apply.
| Message | Level | Cause | What to do |
|---|---|---|---|
Country not found | Shipment | countryIso doesn't match a known country. | Send a valid 2-character ISO country code. |
Postcode not found | Shipment | GB shipments only. The recipient postcode isn't in a serviced postcode area. | Check the postcode. Ask your account manager if the area should be covered. |
Service code not found or not mapped | Shipment | serviceCode isn't enabled on your account for this shipment type. | Use a service code from your account manager. |
Parcel level issue found | Shipment | A marker only. The real reason is on an entry in the parcels array. | Read each parcel's customResponse.errorMessage. |
Route not found | Parcel | No route matches the service, the parcel weight and the destination. | Check the weight and destination. Ask your account manager if the route should exist. |
| A carrier validation message | Parcel | The carrier rejected a field on the parcel. The wording comes from the carrier. | Correct the field named in the message and resend the shipment. |
Ascent refused: {reason} | Parcel | Customs pre-clearance was declined for a US or EU destination. | Correct the customs data (HS code, country of origin, values) and resend. Quote the CorrelationId from the message when you contact support. |
Ascent error: {message} | Parcel | Customs pre-clearance couldn't be completed. | Retry. If it keeps happening, contact support and quote the CorrelationId from the message. |
System issue happened | Batch | The whole batch was abandoned and no shipment was created. | Returned as HTTP 500. Retry the request with the same Idempotency-Key. |
Already created on a previous attempt with this Idempotency-Key; tracking {number}. | Shipment | A retry after an interrupted attempt found the shipment was already created. | Don't resend it. The shipment exists. Use the tracking number in the message to retrieve its label. |