Troubleshooting guide

Check out our API documentation for a list of all the errors our API can return. In this guide, you’ll find simple explanations of how to solve common issues you may encounter while interacting with Stuart’s API.

All errors are listed by category:


The address must be well-formatted and accurate.


This error indicates that our system could not process the address you provided. It may be due to several reasons, the most common being incorrectly formatted or inaccurate address. 

   "message": "The address can't be geocoded"

To verify your address's validity or accuracy you can use this website.

The address must be within Stuart's Zone.


This error indicates that the pick-up or the drop-off address you provided is outside a specific Stuart zone.

⚠️ An address can be inside the drop-off zone but outside the pick-up one (and vice versa).

   "error": "OUT_OF_RANGE",
   "message": "This location is out of range"


This error is returned when the pick-up and drop-off addresses don’t belong to the same zone. Such jobs cannot be created.

   "error": "ADDRESS_INVALID",
   "message": "A destination address is not in a valid delivery area",
   "data": {
       "job.dropoffs.address": [
           "is not in a valid area"

To verify the eligibility of the address:

  • You can call our address validation endpoint to verify the eligibility of the address.
  • You can call our zone coverage endpoint to ensure that both the pick-up and drop-off addresses are within the same zone.
Please make sure to also read this article to learn more about our best practices regarding addresses.

Invalid credentials

The authorization token must still be valid.


This error can happen for different reasons:

  • Expired token: Your token likely expired (tokens have a 30-day validity) and wasn’t renewed.

  • Wrong token:
    • You may be in the wrong environment (for example, you’re in production instead of Sandbox).

    • Some characters may be missing in the token you provided.
  • No token was provided: You may not have included a token in the headers of your request.
   "error": "INVALID_GRANT",
   "message": "The access token was revoked"

How to fix this issue?

  • Go to the Settings page of your dashboard (sandbox or production).
  • In the Integration section, retrieve your Client ID and Client Secret.
  • Generate a new token using the authentication endpoint.
  • Try to send a GET request with the new token in the headers. The token must be populated in the Authorization header. 


GET /v2/jobs/ HTTP/1.1
Authorization: Bearer <token value>
If the request is successful, this means that your previous token had one of the problems listed above. To avoid this issue from recurring in the future, please make sure to read this article and implement our best practices regarding authentication.

Credit card & Payment

The payment details must filled and valid.


This error occurrs when no credit card is linked to your account. To fix it, you must go to the Billing section of your dashboard (Sandbox or Production) and add a credit card.

Note: If you are in Sandbox, you can use any test credit card (other than American Express).

   "error": "CREDIT_CARD_NOT_FOUND",
   "message": "Insufficient funds for client. Please provide a Credit Card"


This error can be shown for different reasons:

  • Your credit card may be expired. If you are in Sandbox, you must add a test credit card and set the expiration date to any date in the future.
  • There are no funds in the bank account associated with your credit card.

Webhook not received

To check your webhook subscription, you must either go to your dashboard in the Settings/API section (Sandbox or Production) or call our get all webhooks endpoint. There you will be able to see all your current subscriptions. To verify your configuration, you must:

  • Check that URL registered on Stuart's system is exactly the same as your API endpoint.
  • Make sure you subscribed to the events you want to listen to.
  • If your endpoint expects authentication headers, ensure you have provided them using the authentication_header and authentication_key in the subscription payload.

If these conditions aren’t met please update your subscription using the dashboard or the webhook update endpoint.

Additionally, if you are in Sandbox, you can subscribe using the URL provided by this website. This way you will be able to check if events are correctly fired and to see our webhook payloads.

Job scheduled at the wrong time

The date must be well-formatted.

As explained in our Setup for Success page, the pickup_at field determines the moment when you want a courier to retrieve a package and therefore whether a job is “instant” or “scheduled”.

The pickup_at field expects a DateTime value (ISO 8601). 

Example: 2023-08-14T13:00:00.000+01:00

The suffix +01:00 is the offset and does not refer to an added hour. It indicates the timezone. All countries are grouped in offsets (e.g. UK +1, central Europe +2). See a full list here

We strongly advise always providing the local time along with the corresponding offset for the time zone where the delivery will take place.

⚠️ It’s important to take daylight saving time into account.

Make sure your system adapts to these time changes and that the suffix is updated accordingly.

The pickup time must be in the future.

   "error": "RECORD_INVALID",
   "message": "Unable to save record",
   "data": {
       "job.pickup_at": [
           "can not schedule a pickup in the past",
           "is not valid"

If you received this error, this means that the pickup_at date you provided was in the past.

To avoid this, you must ensure that the pick-up is always at least 3 minutes after the time you make the request.

Phone number

Phone numbers must be well-formatted.

    "error": "PHONE_INVALID",
    "message": "a destination phone is invalid",
    "data": {
        "job.dropoffs.contact_phone": [
            "is an invalid number"
This error is returned when the phone number provided (for pickup or dropoff) is either incorrect or does not conform to the expected format. Our API expects phone numbers to follow the E.164 standard.

Note: If you use a phone number from a country that is different from the one where the delivery will take place please make sure to include the country code.