Shipment Validation Errors

Carriyo performs validation checks during shipment booking requests, which can lead to errors. There are two levels of validations in Carriyo:

Shipment Creation Validations

These validations are hard checks applied during both shipment creation and updates. If any of these checks fail, the shipment request will be rejected, and the shipment will not be created or updated in Carriyo.

Validation Type Error Code & Response Description Required Header / Parameter
Invalid Credentials 401 Unauthorized
403 Forbidden		 Ensure valid token, API key, and tenant ID are passed. Missing/expired tokens result in unauthorized responses; missing/invalid API key or tenant ID results in forbidden responses. Authorization
x-api-key
tenant-id
Merchant ID 400 Bad Request A valid merchant ID is required. Missing or invalid merchant IDs trigger a bad request response. merchant
Order Reference 400 Bad Request An order reference (typically customer-facing order number) is required. partner_order_reference
Shipment Reference 400 Bad Request A shipment reference is required and must be unique; duplicate references will be rejected. partner_shipment_reference

Shipment Booking Validations

These validations do not prevent shipment creation but will cause the shipment to enter an error state if issues are detected during booking. Booking validations are applied when a booking request is made, so for draft shipments, they only apply when the shipment is confirmed or booked.

1. Invalid Carrier Account

A valid carrier account must be assigned for successful booking. Carriyo automatically assigns this based on automation rules. If no rule matches the shipment’s criteria, the booking will fail, and an error message will be returned.

2. Payment Information

  • Total Amount : Required total monetary value of the shipment.
  • Payment Mode : Specify as PRE_PAID or CASH_ON_DELIVERY (default: PRE_PAID ).
  • Pending Amount : If COD, this field indicates the amount to be collected.

3. Address Details

Address requirements differ based on shipment type:

  • Forward Shipments : Use a predefined location for pickup and full address details for dropoff .
  • Reverse Shipments : Use full address details for pickup and a predefined location for dropoff .
Field Requirement
Contact Name Full name (first and last) is required.
Contact Phone Optional or mandatory per account settings; must be in E.164 format.
Contact Email Optional or mandatory per account settings; must follow RFC 5322 standards.
Address Lines Address Line 1 (street address) required; Address Line 2 optional.
City Required free-text field. Carriyo recommends geo-listed cities for specific countries for carrier compliance.
State Required in countries like the UK, US, and PH.
Country Use the 2-letter ISO country code (e.g., "US" for United States).

4. Item / SKU Details

At least one item or SKU is required for each shipment booking:

  • SKU : The unique identifier for the item.
  • Item Price : Unit price after discounts.
  • Item Quantity : Number of units of the SKU included in the shipment.

5. Parcel Details

Parcel details are optional but required by most carriers for successful booking:

  • Parcel Weight : Weight in kilograms.
  • Parcel Dimensions : Height, width, and depth in centimeters.

Carrier Errors

Even after passing Carriyo’s booking validations, carriers may still reject the booking due to additional carrier-specific validations or system issues. In these cases, the shipment will be set to an error status.

  • Carrier Technical Errors
    Carriyo has an auto-booking retry mechanism that automatically retries the booking if it fails due to technical issues on the carrier's end (e.g., 5xx errors or API timeouts).
  • Carrier Validation Errors
    If the carrier rejects the booking request due to data-related issues (e.g., 4xx errors), the shipment will remain in error status until it is manually updated and reprocessed in the Carriyo Dashboard.