Innoship

Define own error message subcategory: - Your own subcategories for courier errors

Overview

Every failed order now carries two extra fields, Category and Subcategory, that tell you at a glance why the order failed and who needs to act. The original error message is unchanged; the two fields are added next to it.

You will find them in:

• API error responses for order creation (single order, multiple orders and the v2 shipments endpoint), as categoryCode and subcategoryCode.
• The Failed requests screen in the Innoship portal, where you can filter failed orders by category and subcategory.

Use them to route errors to the correct team, build reports on why orders fail, or trigger automatic handling in your own systems.

{
  "Errors": [
    {
      "Message": "An Order with Reference: (389012644) already exists. Awb: [BOKM10013531]",
      "Details": [],
      "CategoryCode": "VALIDATIONS",
      "SubcategoryCode": "BUSINESS_VALIDATION"
    }
  ],
  "CorrelationId": "f6f8c17dedb01f1274457412c388718f"
}

How to read the fields

Category tells you the area of the problem and who usually fixes it. Subcategory names the specific cause inside that area. 

There are 6 categories:

Categories and subcategories

Each category below lists every subcategory it can contain, what it means and what to do about it.

VALIDATIONS

The order data has a problem. Correct it and send the order again.

CONFIGURATIONS

Settings in Innoship prevent the order. Most can be fixed in your account settings.

COURIER_RESTRICTIONS

The courier does not accept this shipment. Choose another courier or service, or change the shipment.

PRICING

The shipping price could not be calculated. Check the price list for the courier and service, or contact Innoship support.

COURIER_ERROR

The courier's system rejected the order or did not answer. The error message contains the courier's own text. This is the only category where you can add your own subcategories (see the next section).

INTERNAL

Something failed on the Innoship side. Retry the order; if it keeps failing, contact Innoship support and include the correlation ID from the response.

Your own subcategories for courier errors

Courier errors vary a lot between couriers, so you can split COURIER_ERROR into your own subcategories. A rule looks for a text in the courier's error message and, when it is found, returns your subcategory code instead of the default one.

Example: a rule with the text "Invalid county" and the code WRONG_COUNTY. A failed order whose courier message contains "Invalid county" returns COURIER_ERROR / WRONG_COUNTY.

To set up rules:

1. In the Innoship portal, open the Connect => Settings page and find the Failed requests settings panel.
2. Click Add and fill in the subcategory name, the subcategory code and the text to look for.
3. Choose how the text is matched: Contains (plain text, case does not matter, at least 3 characters) or Regex (a pattern, for advanced users).
4. Click Save. The rule applies to new failed orders right away.

How rules behave:

• Rules are checked in the order they were created; the first one that matches wins.
• Rules apply to all couriers and only to the COURIER_ERROR category.
• Each code can be used once and cannot be one of the Innoship codes listed above.
• To group several texts under one code, use a single Regex rule, for example dimensions exceeded|size too big.
• API responses return only the code. The portal shows your subcategories as "Name (CODE)".
• Changing or deleting a rule does not change failed orders recorded before. If a rule is deleted, its past failed orders show "rule deleted".

Good to know

• Failed orders recorded before this feature was released have no category or subcategory.
• A request that cannot be read at all (malformed JSON) is rejected without a category.
• v2 shipments API: categoryCode used to hold C001-C004. It now holds the category codes from this guide, and category holds the same value. Update any integration that checks the old C00x values.
• The new fields are always included in error responses. If your integration rejects unknown fields, allow categoryCode and subcategoryCode.