Error codes

When creating, updating, or booking a shipment, Carriyo may return error codes attached to the shipment. Each code has a severity. ERROR codes block booking until corrected. WARNING codes don't block booking but flag data that may cause issues with some carriers.

Required data

Error code	Level	Description
required_data_missing	ERROR	Required data is missing. Provide the missing field and reprocess.
required_data_invalid	ERROR	Required data is invalid. Provide a valid value and reprocess.
merchant_missing	ERROR	The Merchant provided was not found.
default_merchant_not_configured	ERROR	No default Merchant is configured for the tenant. Provide a valid Merchant.

Contact details

Error code	Level	Description
phone_number_missing_error	ERROR	Phone number is required and was not provided.
phone_number_missing_warning	WARNING	Phone number is missing, required by some carriers.
phone_number_invalid	ERROR	The phone number provided is invalid.
phone_number_unknown	WARNING	The phone number provided may not be valid.
email_invalid	ERROR	The contact email provided is invalid.
email_missing_error	ERROR	Contact email is required and was not provided.
email_missing_warning	WARNING	Contact email is missing, required by some carriers.

Address & geo

Error code	Level	Description
coordinates_invalid	ERROR	The provided coordinates are incorrect. Provide valid latitude and longitude.
coordinates_latitude_invalid	ERROR	The provided latitude is invalid. Valid range is [-90, 90].
coordinates_longitude_invalid	ERROR	The provided longitude is invalid. Valid range is [-180, 180].
country_invalid	ERROR	The country code provided is invalid. Use a valid 2-letter ISO 3166 code.
state_invalid	ERROR	The state provided is invalid for the given country.
postcode_missing	WARNING	The postcode is missing.
postcode_invalid	ERROR	The postcode provided is not valid for the given country.
address_field_not_found	ERROR	A referenced address field was not found in the resolved address.
address_free_form_not_subscribed	ERROR	Your account is not subscribed to use free-form addresses. Use a predefined location.
address_code_type_invalid	ERROR	An address code type provided is not recognized.
duplicated_address_code_type	ERROR	The same address code type appears more than once.
invalid_address_code_for_country	ERROR	The provided address code is not accepted for the destination country.
partner_location_invalid	ERROR	The provided location does not exist.
partner_location_not_active	WARNING	The provided location is not active.
time_slot_invalid	WARNING	The TimeSlot provided does not exist.

Carrier assignment

Error code	Level	Description
carrier_account_invalid	ERROR	The carrier account provided does not exist.
invalid_input_carrier	ERROR	The carrier name provided for a pre-booked shipment is not recognized by Carriyo.
no_carrier_assigned	ERROR	No carrier account was assigned to the shipment.
no_automation_rule_set_found	ERROR	No automation rule set is configured for this merchant; the shipment cannot be auto-assigned.
multiple_automation_rule_sets_found	ERROR	More than one automation rule set matches; configuration is ambiguous.

Items

Error code	Level	Description
items_missing	ERROR	At least one item is required on the shipment.
item_hscode_missing	WARNING	Item HS code may be required for cross-border shipments.
item_origin_country_missing	WARNING	Item origin country may be required for cross-border shipments.
item_origin_country_invalid	ERROR	Item origin country code is not a valid ISO 3166 country code.
item_weight_missing	WARNING	Item weight may be required for cross-border shipments.
item_missing_in_parcel	WARNING	An item on the shipment is not present in any parcel's parcel_items mapping.

Parcels & packages

Error code	Level	Description
parcel_info_missing	WARNING	Parcel information may be required by the carrier. Provide at least one valid parcel.
parcel_info_ambiguous	ERROR	Parcel information is ambiguous (e.g. items spread inconsistently across parcels).
parcel_item_invalid	ERROR	Parcel items contain invalid data (e.g. quantity exceeds the item's quantity on the shipment).
parcel_weight_missing	WARNING	Parcel weight may be required by the carrier.
parcel_weight_exceeds	ERROR	A parcel weight exceeds the carrier's maximum allowed weight.
parcel_dimensions_missing	WARNING	Parcel dimensions may be required by the carrier.
freight_weight_exceeds	ERROR	The total freight weight exceeds the carrier's maximum allowed weight.
package_reference_not_unique	ERROR	A package reference is reused; package references must be unique within a shipment.
package_hierarchy_invalid	ERROR	The package hierarchy contains an invalid parent reference.
package_circular_reference	ERROR	The package hierarchy contains a circular parent reference.
package_weight_invalid	ERROR	A package weight is invalid (negative, zero, or non-numeric).
measurement_system_mixed	ERROR	The shipment mixes metric and imperial units; pick one system per shipment.

Payment

Error code	Level	Description
payment_method_invalid	ERROR	The payment method is invalid. Allowed: PRE_PAID or CASH_ON_DELIVERY.
payment_currency_invalid	ERROR	The payment currency is invalid. Use a valid ISO 4217 code.
payment_pending_amount_invalid_for_cod	ERROR	The pending amount for CASH_ON_DELIVERY is invalid. Provide a value greater than zero.
payment_pending_amount_invalid_for_prepaid	ERROR	The pending amount for PRE_PAID is invalid. Set to zero or omit.
amount_exceeds_limit	ERROR	A monetary amount exceeds the allowed limit (999,999,999).

Custom attributes

Error code	Level	Description
custom_attribute_invalid	ERROR	The custom attribute name does not exist for this tenant.
custom_attribute_not_subscribed	ERROR	Your account is not subscribed to use custom attributes.
custom_attribute_value_invalid	ERROR	Invalid value provided for the custom attribute.
custom_attribute_value_max_length_exceeded	ERROR	Custom attribute value exceeds the 100-character limit.

Cross-border / customs

Error code	Level	Description
incoterms_invalid	ERROR	The incoterm provided is not supported by the assigned carrier.
registration_number_type_invalid	ERROR	A registration number type is not recognized (must be one of VAT, IOSS, EOR, EIN, GST, etc.).
battery_material_type_invalid	ERROR	Battery material type is not recognized (lithium_ion or lithium_metal).
battery_packing_type_invalid	ERROR	Battery packing type is not recognized (contained_in_equipment, packed_with_equipment, stand_alone).

Documents & labels

Error code	Level	Description
label_format_invalid	ERROR	The requested label format is invalid. Allowed: PDF, PNG, ZPL.
weight_unit_invalid	ERROR	The weight unit is invalid. Allowed: KG.
dimension_unit_invalid	ERROR	The dimension unit is invalid. Allowed: CM.
template_parsing_failed	ERROR	A document template failed to parse, likely a syntax error in the template configuration.

Source / lifecycle

Error code	Level	Description
source_type_invalid	WARNING	The shipment source type provided is invalid.
status_change_not_allowed	ERROR	The requested status change is not permitted from the shipment's current state.
prebooked_tracking_error	ERROR	Carriyo could not initiate tracking for the pre-booked shipment (carrier rejected the lookup).
collection_scheduled_dates_invalid	ERROR	The collection schedule from/to dates are invalid (in the past, inverted, or outside carrier windows).
delivery_scheduled_dates_invalid	ERROR	The delivery schedule from/to dates are invalid.

Carrier integration

Error code	Level	Description
shipment_id_not_generated	ERROR	The carrier returned a successful response but did not generate a tracking number.
timeout	ERROR	The carrier API timed out. Carriyo will retry automatically.
unexpected_response	ERROR	The carrier returned a response Carriyo could not parse.
error_response	ERROR	The carrier returned an error response. See the shipment's error_history for details.

Order & fulfillment

Error code	Level	Description
location_id_missing_in_fulfillment_order	ERROR	The fulfillment order is missing a location_id.
open_line_item_id_invalid	ERROR	A line item ID referenced in the fulfillment order does not exist on the order.
order_line_item_weight_unit_missing	ERROR	An order line item is missing the weight unit needed to compute fulfillment weight.
invalid_items_in_fulfillment_order	ERROR	One or more items on the fulfillment order are invalid.
invalid_fulfillment_id_in_fulfillment_order_update_request	ERROR	The fulfillment_id in an update request does not match an existing fulfillment order.
partner_location_is_not_an_collection_location	ERROR	The location referenced is not configured as a collection location.
delivery_address_missing_in_fulfillment_order	ERROR	The fulfillment order has no delivery address.
customer_collection_address_missing_in_fulfillment_order	ERROR	A customer-collection fulfillment order is missing the customer's address.
delivery_option_invalid	ERROR	The delivery option referenced does not exist.

Deprecated codes

The following codes are still emitted for backwards-compatibility but should not be relied on for new integrations:

Error code	Replacement
email_missing	email_missing_error / email_missing_warning
phone_number_missing	phone_number_missing_error / phone_number_missing_warning
collection_scheduled_dates_are_in_the_past	collection_scheduled_dates_invalid