Error Navigation

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
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
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
1 Like