Validation errors

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

Shipment creation validations

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

Validation type	Error & 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.	merchant
Order reference	400 Bad Request	An order reference (typically the customer-facing order number) is required.	partner_order_reference
Shipment reference	400 Bad Request	A shipment reference is required and must be unique; duplicates are rejected.	partner_shipment_reference
Maximum items	400 Bad Request	Maximum number of items allowed is 250.	items
Maximum parcels	400 Bad Request	Maximum number of parcels allowed is 250.	parcels
Maximum packages	400 Bad Request	Maximum number of packages allowed is 250.	freight.packages
Description length	400 Bad Request	Maximum length for all descriptions is 1000 characters. Applies to item, parcel, pickup, and dropoff notes.	description, notes
Reference length	400 Bad Request	Maximum length for all references is 250 characters.	partner_shipment_reference, partner_order_reference, alternate_reference, other_references, partner_parcel_reference, package_reference

Shipment booking validations

These validations don't prevent shipment creation but cause the shipment to enter an error state if issues are detected during booking. For draft shipments, these checks apply only when the shipment is confirmed or booked.

1. Invalid carrier account

A valid carrier account must be assigned for successful booking. Carriyo automatically assigns one based on automation rules. If no rule matches the shipment's criteria, the booking will fail.

2. Payment information

• Total amount: required total monetary value of the shipment.
• Payment mode: PRE_PAID or CASH_ON_DELIVERY (default PRE_PAID).
• Pending amount: for COD, the amount to be collected.

3. Address details

Address requirements differ based on shipment type:

• Forward shipments: predefined location for pickup, full address details for dropoff.
• Reverse shipments: full address details for pickup, 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.
Address lines	Address Line 1 (street address) is required; Address Line 2 is optional.
City	Required free-text. Carriyo recommends geo-listed cities for specific countries, see Geo list.
State	Required in countries like the UK, US, and PH.
Country	Use the 2-letter ISO country code (e.g. US).

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, 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. The shipment will be set to an error status.

• Carrier technical errors: Carriyo has an auto-booking retry mechanism that automatically retries on carrier-side technical issues (5xx errors, API timeouts).
• Carrier validation errors: if the carrier rejects the booking due to data-related issues (4xx errors), the shipment remains in error until manually corrected and reprocessed.