Stuart Error Navigation
When using the Stuart API you may encounter some error messages if certain features are not implemented correctly, or if certain fields are not populated correctly. This guide aims to go through some of the most common errors and suggestions to address them.
If you haven’t already, please look through our tips and best practices.
If the error displayed in this guide is not displayed here please check out the Error Documentation here, and failing that, please comment on this post down below.
Typical Job Errors
Firstly, please ensure that all required fields are populated. If operating in France please make sure to specify transport_type and elsewhere please be sure to specify package_type.
You can see the full list of required fields here.
Doing so will avoid 400 errors.
For a comprehensive list of 422 errors when creating a job and our initial troubleshooting suggestions for them please look here:
| RECORD_INVALID | Unable to save record: a valid phone number is required due to low address accuracy | The address is not accurate enough and needs a phone number. Although not required, we would always recommend specifying the customer phone number. It significantly increases delivery success rate. Please see this guide on how to format numbers: How should I format phone numbers? |
| RECORD_INVALID | Unable to save record: Package size {package_type} is not allowed |
This is required for all countries except France. Please use one of these options: xsmall, small, medium, large, xlarge |
| PHONE_INVALID | a origin/destination phone is invalid | Please see this guide on how to format numbers: How should I format phone numbers? |
| EMAIL_INVALID | a origin/destination email is invalid | Please make sure the email address is valid or retry without including it. |
| JOB_DISTANCE_NOT_ALLOWED | Job distance exceeded the maximum range of the selected transport type | Please verify that the source and destination addresses make sense for that order and were what was intended. Try to ensure that the correct or nearest of your stores is always being selected for that customer address during the order process. Failing this: Please either change the job distance or request a different transport type for your job. |
| JOB_INVALID_DUPLICATED_ORDER_ID | Provided order ID is already used | This commonly occurs when a client supplies multiple orders with the same value in the client reference field - this is what we understand by an order ID. Please verify from your logs or order history there are no duplicate requests |
| ADDRESS_INVALID | A destination address is not in a valid delivery area | Do not retry and investigate if your deliveries are within valid Stuart zones by using the get zones endpoint, and also by checking the validate address endpoint to verify the address exists. |
| UNKNOWN | TransportType with {transport_type} does not exist |
This is for France only. Please use one of the following: bike, cargobike, cargobikexl, motorbike, motorbikexl, car, van. |
| CANT_GEOCODE_ADDRESS | The address can’t be geocoded | Please retry with just City and Postcode per our address best practices |