Troubleshooting guide

{
   "error": "CANT_GEOCODE_ADDRESS",
   "message": "The address can't be geocoded"
}

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

{
   "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.

{
   "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. 

Example:

GET /v2/jobs/ HTTP/1.1
Host: api.sandbox.stuart.com
Authorization: Bearer <token value>

Credit card & Payment

The payment details must filled and valid.

CREDIT_CARD_NOT_FOUND

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"
}

PAYMENT_DECLINED

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.