Avoiding common job creation errors

Hoping to avoid errors when creating jobs through the Stuart API? Here are some useful tips and resources to help! Note: You can find a full list of errors in our API documentation, as well as examples of main job creation errors here.

Zone coverage

  • The Get Zone Coverage endpoint can help you to identify picking or delivery coverage per city, this information can be used to restrict your offering of Stuart delivery to your stores or customers.

  • We’d advise validating your customers delivery address early in the order flow by referencing the Get Zone Coverage results or simply calling our validate address endpoint.

  • Note: Picking zone coverage may be covered in conversations between our commercial teams, so you may know your stores are within coverage without any additional technical validation required.

Operational hours

  • You can send us orders that are scheduled during hours when we are not operating, but you cannot create instant orders outside of operational hours.

  • The get scheduling slots endpoint can be used to fetch ‘slots’ that could be displayed straight to your customer or used to infer our opening hours.

  • Note: You may already know that your operational hours fit into ours, or you may have commercial agreements with us as to your operational hours.

Job distance

  • There are restrictions on the maximum distance of jobs you can create with Stuart, you can read more on this topic in this Q&A post.

  • These restrictions depend on the package size or transport type that you would like to request, check out understanding package size for more details.

  • To validate job distance before sending it to the Stuart API, you can use an external API such as Google Directions to find the distance between an origin and destination.

Contact details

  • Contact phone numbers are required if the address that you provide is deemed ‘too approximate’ by our geocoding validation, so to reduce potential related errors and to provide our drivers with the best chance to find the given addresses, we recommend that you provide phone numbers. Check out How should I format phone numbers? to also be sure to avoid phone validation errors.

  • Provide the first AND last name OR company name, more detail in Job Creation Small Change Coming

  • Add clear identifiers in the ‘pickups[0].company’ field of the job creation request of the company name and store name for example ‘Pizza Co. - Walton Store’


  • Specifying a client reference will act as a unique identifier for the job you create, allowing you to have this ID in all your webhook events, easily linking your updates to your order.
    To find out more about why you should specify a client_reference and our recommendations on how to format them, see this FAQ post.


Last but not least, check out our address best practices in What are the addresses best practices?