Common API Error Responses

Overview

MachShip does its best to return meaningful error messages when there is something wrong with the API calls.

Error Response Format

If there is any error, MachShip will return a response that looks similar to the one below:

{  
   "object": null,
   "errors": [  
      {  
         "validationType": "Error",
         "memberNames": [],
         "errorMessage": "ConsignmentIds are required"
      }
   ]
}

Common Error Messages

Error Message Error Explanation
Field Name is/are required Required field(s) are missing from the request
An unexpected error has occurred. The MachShip team has been notified Could be a provided value does not exist in MachShip
Unable to find [Entity Name] or you do not have access The given ID might exist in MachShip but the current user doesn't have access/privilege to see it
No [Entity Name] were found Cannot find an object by the given criteria
String is not a valid email address Email field is assigned an invalid email value
Cannot set both ReceiverAccountCode and ReceiverAccountId Only need to provide one of them
From/To Location is invalid. Check that the location ID that was entered is a valid Location ID Location can be specified by either Location ID or a combination of Suburb and Post Code. When a Location ID is provided, it needs to be a valid one
From/To Location is invalid. Check that the suburb/postcode combination is correct Location can be specified by either Location ID or a combination of Suburb and Post Code. When the latter is provided, it needs to be correct
No prices were found No available routes/prices found based on the request's data
Item quantity is required and must be greater than 0 Any quantity field is required and it must be greater than 0
Newtonsoft.Json.JsonReaderException: After parsing a value an unexpected character was encountered... The JSON request is invalid
No Consignment IDs have been provided. Ensure that you are passing in an array of IDs When the endpoints expect to get a list of Consignment IDs and there are none
Cannot manifest as some of these consignments are no longer unmanifested. Please review the selected unmanifested consignments and try again It is a specific error when using Manifest endpoints
Dangerous Goods / No Dangerous Goods must be declared When a company has DG enabled, every request to create a consignment will need to declare whether DGs are included or not
Route is not Dangerous Goods route yet Dangerous Goods have been declared It is when the service you choose doesn't allow DG but you have specified a DG in the item list
No routes were found using your carrier accounts No routes available for the selected carrier account(s)

Error Handling Best Practices

When working with MachShip's API, consider these error handling practices:

  1. Always check the errors array

    • The errors array may contain multiple error messages
    • Each error provides specific validation information
    • The memberNames array may indicate which fields caused the error

  2. Handle common scenarios

    • Missing required fields
    • Invalid data formats
    • Access permission issues
    • Invalid location combinations

  3. Implement appropriate retries

    • Do not retry validation errors
    • Consider retrying unexpected errors
    • Implement exponential backoff for retries