Skip to Content
FastracDocs

Errors

Every error the Shipping Engine API returns, what causes it and how to fix it.

Product
APIShipping Engine API
Section
Reference
Reading time
20 min read

Shipping Engine uses standard HTTP status codes. Every error has the same shape:

{
  "statusCode": 400,
  "message": "insurance parameter is required for regular shipments (cannot be empty)",
  "error": "Bad Request"
}

When several fields fail validation, message is a list, one entry per problem:

{
  "statusCode": 400,
  "message": [
    "packages.0.itemValue must not be less than 15000",
    "origin.subdistrictId must be a number string"
  ],
  "error": "Bad Request"
}

A few errors also carry a machine-readable code and extra fields. Branch on code when it is present, not on the text of message:

{
  "statusCode": 400,
  "code": "PICKUP_SCHEDULE_EXPIRED",
  "message": "Pickup schedule must be at least 15 minutes ahead (Asia/Jakarta, UTC+7)."
}

Messages are in English, except a few that are written for end customers in Indonesian. Values such as codes, amounts and IDs inside a message change from request to request. In this page they are shown as … or as an example value.

Status codes

StatusMeaningRetry?
400The request is invalid. Fix it before retrying.No
401The token is missing, expired or invalid.After getting a new token
403Your API key's role lacks a permission, or the resource isn't yours.No. Ask your admin.
404Nothing was found, for example no courier serves the route.No
422The request is valid but not allowed in the current state.No
500Something went wrong on our side.Yes, with backoff

At a glance

AreaStatusMessage (starts with)Entry
Auth401Missing authorization header, Invalid authorization schemeToken problems
Auth401"exp" claim timestamp check failed, signature verification failedToken rejected
Auth401OAuth client is not registered in the app …Client not registered
Auth401Organization owner is not …Organisation owner missing
Auth403You're not authorized to access this resource (Missing permissions: …)Missing permission
Validation400list of field messagesValidation errors
Regions400Query parameter '…' is required. / must be a valid number.Region parameter missing
Regions400Field 'keyword' is required.Search keyword missing
Regions400Query parameter 'postCode' is required.Postcode missing
Couriers400"courier_code" is not allowed to be empty, Invalid courier_code '…'.Courier code invalid
Couriers400Invalid courier type. …, Invalid isEnabled value. …Courier filter invalid
Rates400insurance parameter is required …Insurance is required
Rates400packages.0.itemValue must not be less than 15000Item value too low
Rates400vehicle should not be emptyVehicle missing
Rates400stopOrder is required …, stopOrder must be unique …Destinations need a stop order
Rates400Courier adapter for … was not found.Unknown courier
Rates400Selected courier service does not support insurance …Insurance not supported
Rates400Custom COD amount cannot be less than …Custom COD too low
Rates400COD amount (Rp …) exceeds the maximum COD …COD above the courier's limit
Rates403You are not allowed to use COD for shipping rate COD.Missing COD permission
Rates404No shipping rates available …No rates available
Rates404Shipping rate with code '…' not found or unavailableRate not found
Orders400Invalid shipping rate code provided.Invalid rate code
Orders400Shipping rate code '…' have expired.Rate expired
Orders400Courier service '…' is currently not available.Service unavailable
Orders400… is disabled for one or more package categories.Package category not allowed
Orders400Total package weight …, Package dimensions exceed …Vehicle capacity exceeded
Orders400All shipments in one order must be either COD or non-COD.COD and non-COD mixed
Orders400Courier service '…' (…) does not support COD.COD not supported
Orders403You are not allowed to use COD for COD orders.COD not allowed
Orders400… does not support pickup. / … does not support dropoff.Fulfilment method not supported
Orders400Pickup shipments require sender coordinates.Sender coordinates required
Orders400code: PICKUP_SCHEDULE_EXPIREDPickup schedule too soon
Orders400code: PICKUP_SCHEDULE_NOT_QUOTEDPickup schedule not quoted
Orders400shippingOptions.schedule must be a valid ISO 8601 datetime.Invalid pickup schedule
Orders400Receiver details are missing for shipping rate destinations.Receiver details missing
Orders400Payment failed, but order '…' was created successfully. Reason: …Payment failed
Cancel order404 / 403Order with code '…' was not found. / You are not allowed to cancel order '…'.Order not found
Cancel order400Order '…' cannot be cancelled because shipment '…' is already delivered.Order has a delivered shipment
Cancel order400Order '…' has no shipments to cancel.Order has no shipments
Shipments422Invalid startDate filter., startDate cannot be later than endDate.Invalid date range
Shipments404 / 403Shipment with code … not found. / You are not allowed to view this shipment.Shipment not found
Shipments400Shipment '…' has not been dispatched yet.Not dispatched yet
Shipments404Shipment with code or airway bill '…' not found.Tracking code not found
Shipments400Shipment '…' is delivered and cannot be cancelled.Cannot cancel a delivered shipment
Shipmentsvariesthe courier's reasonCourier refused the cancellation
Sandbox403Simulate shipment status is not allowed in PRODUCTION environment.Simulation in production
Sandbox400Shipment … not found.Simulation shipment not found
Webhooks400Webhook URL must start with https://Webhook URL must be HTTPS
Webhooks400secret must be longer than or equal to 32 charactersWebhook secret too short
Webhooks422The webhook URL could not be verified. …Webhook verification failed
Server500Internal server errorServer error

Authentication and permission errors

Token problems

401 · Missing authorization header · Invalid authorization scheme · expired token

Cause: the Authorization header is missing, or it doesn't use the Bearer scheme. Fix: send Authorization: Bearer <access_token>, and request a new token when the old one expires.

Token rejected

401 · "exp" claim timestamp check failed 401 · signature verification failed · Invalid Compact JWS · unexpected "aud" claim value

Cause: the access token has expired, is malformed, was issued for another environment (for example a sandbox token sent to production), or was not issued for the Shipping Engine API. Fix: request a new token from the token URL of the same environment you call, and send it unchanged. Cache tokens and refresh them shortly before they expire. See Authentication.

Client not registered

401 · OAuth client is not registered in the app (No IdP subject matches organizations auth_provider_client_id).

Cause: the token is valid, but its client is not linked to a Shipping Engine organisation. This happens with credentials that don't belong to an approved business account. Fix: use the client_id and secret of your organisation's API key, from the API keys page of the dashboard. If they are correct, contact support.

Organisation owner missing

401 · Organization owner is not configured for this client. 401 · Organization owner is not registered. · Organization owner is not linked to this organization.

Cause: an API key acts as the owner of your organisation, and that owner account can't be found or has left the organisation. Fix: contact support. These errors can't be fixed from your side.

Missing permission

403 · You're not authorized to access this resource (Missing permissions: CREATE_ORDER).

Cause: the role of your organisation owner doesn't include the permission the endpoint needs. Your API key always has the owner's permissions. Fix: ask an organisation admin to add the permission to the owner's role. See Permissions for which endpoint needs which permission.

Validation errors

400 · message is a list, for example:

{
  "statusCode": 400,
  "message": [
    "shipments.0.receivers.0.addressNote should not be empty",
    "shipments.0.shippingOptions.schedule must be a valid ISO 8601 date string"
  ],
  "error": "Bad Request"
}

Cause: one or more fields have the wrong type, are missing, or are out of range. Each entry names the field by its path (shipments.0.receivers.0 is the first receiver of the first shipment). Fix: correct every listed field and send the request again. Fields that the API doesn't know are ignored, not rejected, so check the spelling of optional fields against the API reference.

Region errors

Region parameter missing

400 · Query parameter 'provinceId' is required. 400 · Query parameter 'cityId' must be a valid number.

Cause: listCities, listDistricts or listSubdistricts was called without its parent ID (provinceId, cityId, districtId), or with a value that isn't a number. Fix: pass the numeric id of the parent region from the previous list.

Search keyword missing

400 · Field 'keyword' is required.

Fix: send a non-empty keyword to searchRegions. An unknown keyword is not an error: you get an empty list.

Postcode missing

400 · Query parameter 'postCode' is required.

Fix: send postCode to lookupPostcode. A postcode with no match returns an empty list.

Courier errors

Courier code invalid

400 · "courier_code" is not allowed to be empty 400 · Invalid courier_code 'XYZ'.

Fix: pass a courier code from listCouriers to listCourierServices, for example courier_code=JNE. See Couriers.

Courier filter invalid

400 · Invalid courier type. Allowed values: INSTANT, REGULAR 400 · Invalid isEnabled value. Allowed values: true, false, 1, 0

Fix: use type=INSTANT or type=REGULAR, and isEnabled=true or false.

Shipping rate errors

Insurance is required

400 · insurance parameter is required for regular shipments (cannot be empty)

Cause: you left out insurance for a regular courier, or for REGULAR or ALL. Fix: send "insurance": true or "insurance": false. Only PAXEL, LALAMOVE, GRAB and DASH allow leaving it out.

Item value too low

400 · packages.0.itemValue must not be less than 15000

Cause: itemValue is below Rp 15.000 or above Rp 100.000.000. Fix: declare the real value of the goods, between those limits.

Vehicle missing

400 · vehicle should not be empty

Cause: courierCode is PAXEL, LALAMOVE, GRAB, DASH or INSTANT, but vehicle is not set. Fix: add "vehicle": "BIKE", or another vehicle the parcel fits.

Destinations need a stop order

400 · stopOrder is required for each destination when multiple destinations are provided. 400 · stopOrder must be unique for each destination.

Fix: number your destinations 1, 2, 3… with no duplicates.

Unknown courier

400 · Courier adapter for XYZ was not found.

Cause: courierCode is not a supported code. Fix: use a code from the courier table, or REGULAR, INSTANT or ALL.

Insurance not supported

400 · Selected courier service does not support insurance premium calculation.

Fix: quote this courier with "insurance": false, or choose another courier.

Custom COD too low

400 · Custom COD amount cannot be less than totalPrice + COD fee + PPN COD (Rp 14820)

Cause: codOption.codCustomAmount doesn't cover the shipping costs. Fix: raise it to at least the amount in the message, or remove it to use standard COD. See COD.

COD above the courier's limit

400 · COD amount (Rp 6250000) exceeds the maximum COD of Rp 5000000 for courier SPX.

Fix: choose another courier, or lower the order value.

Missing COD permission

403 · You are not allowed to use COD for shipping rate COD.

Fix: ask your account admin to enable COD for your organisation, or quote without codOption.

No rates available

404 · No shipping rates available for the requested route or parameters.

Cause: no courier can carry this parcel on this route. Common reasons: the parcel is too heavy or large for the service or vehicle, the area isn't served, or COD isn't available there. Fix: check the subdistrictId values, the weight and the dimensions. Try courierCode: "ALL". In a checkout, show "no shipping options for this address".

Rate not found

404 · Shipping rate with code 'SR-…' not found or unavailable

Fix: check the code. It must come from a previous rate response.

Order errors

These come from POST /b2b/orders. Unless the entry says otherwise, the order is not created and nothing is charged.

Invalid rate code

400 · Invalid shipping rate code provided.

Cause: a shippingRateCode doesn't exist. Fix: use the shippingRateCode exactly as returned by createShippingRates in the same environment.

Rate expired

400 · Shipping rate code 'SR-…' have expired.

Cause: the rate's validUntil has passed. Fix: request a new rate, show the new price to your customer, and create the order with the new code. See How long a rate lasts.

Service unavailable

400 · Courier service 'JNE REG' is currently not available.

Cause: the courier service was switched off after you got the rate, for example during a courier outage. Fix: request new rates and choose another service.

Package category not allowed

400 · Courier service 'REG' (JNE) is disabled for one or more package categories.

Cause: the service doesn't accept one of the package types in the rate. Fix: choose another courier, or quote again with the correct package type.

Vehicle capacity exceeded

400 · Total package weight (…g) exceeds the maximum capacity of vehicle '…' (…g). 400 · Package dimensions exceed the maximum capacity of vehicle '…' (…x…x…cm).

Cause: for an instant courier, the packages are heavier or larger than the vehicle you quoted. Fix: quote again with a bigger vehicle, or split the parcel into several shipments.

COD and non-COD mixed

400 · All shipments in one order must be either COD or non-COD.

Fix: put COD shipments and non-COD shipments in separate orders.

COD not supported

400 · Courier service 'REG' (JNE) does not support COD.

Fix: choose a rate whose isSupportCod is true, or quote without COD.

COD not allowed

403 · You are not allowed to use COD for COD orders.

Cause: the rate uses COD, but your API key's role doesn't have the USE_COD permission. Fix: ask an organisation admin to add USE_COD to the owner's role. See Permissions.

Fulfilment method not supported

400 · Courier service 'REG' (JNE) does not support pickup. 400 · Courier service 'REG' (JNE) does not support dropoff.

Cause: shippingOptions.fulfillmentMethod (or its default) isn't offered by this service. When you leave it out, instant services default to PICKUP and other services to DROPOFF. Fix: check isSupportPickup and isSupportDropOff on the rate and send a method it supports.

Sender coordinates required

400 · Pickup shipments require sender coordinates.

Cause: a regular (non-instant) shipment uses PICKUP, but sender.coordinate is missing. Fix: send sender.coordinate with latitude and longitude (as strings), or use DROPOFF.

Pickup schedule too soon

400 · code: PICKUP_SCHEDULE_EXPIRED

{
  "statusCode": 400,
  "code": "PICKUP_SCHEDULE_EXPIRED",
  "message": "Pickup schedule must be at least 15 minutes ahead (Asia/Jakarta, UTC+7)."
}

Cause: shippingOptions.schedule is less than 15 minutes in the future, Jakarta time (WIB). Fix: send a later time with an offset, for example 2026-11-21T09:00:00+07:00, or leave schedule out to use the default. See Pickup scheduling.

Pickup schedule not quoted

400 · code: PICKUP_SCHEDULE_NOT_QUOTED

{
  "statusCode": 400,
  "code": "PICKUP_SCHEDULE_NOT_QUOTED",
  "message": "Jadwal pickup tidak sesuai dengan ongkir yang dipilih. Hitung ulang ongkir dengan jadwal tersebut, atau pesan tanpa jadwal untuk pickup secepatnya.",
  "quotedScheduledAt": "2026-11-21T09:00:00+07:00",
  "requestedScheduledAt": "2026-11-21T13:00:00+07:00"
}

Cause: for an instant LALAMOVE, DASH or BLITZ rate, the pickup time is fixed by the quote. You sent a schedule that differs from the scheduledAt the rate was quoted with. Fix: leave schedule out (the quoted time is used), send the same time as quotedScheduledAt, or quote again with the new time.

Invalid pickup schedule

400 · shippingOptions.schedule must be a valid ISO 8601 datetime.

Fix: send an ISO 8601 date and time, for example 2026-11-21T09:00:00+07:00. A time without an offset is read as Jakarta time (WIB).

Receiver details missing

400 · Receiver details are missing for shipping rate destinations.

Fix: send one entry in receivers for each destination of the rate, in the same order.

Payment failed

400 · Payment failed, but order 'FSO-261120-ABC123' was created successfully. Reason: Insufficient balance.

Cause: the order passed validation and was created, but paying for it or booking the courier failed. The order stays DRAFT, and anything charged is refunded. The text after Reason: tells you why. The most common reasons are below.

Fix: don't retry the same order. Fix the reason, then create a new order with fresh rates. You can cancel the leftover DRAFT order with cancelOrder.

Insufficient balance

Reason: Insufficient balance.

Cause: your shipping credit is lower than the total totalPrice of the non-COD shipments in the order. (COD orders are not charged upfront.) Fix: top up your balance in the dashboard, then create a new order. Check your balance first with retrieveBalance.

Shipping rate expired before payment

Reason: Tarif LALAMOVE untuk pesanan ini sudah kedaluwarsa. Silakan cek ongkir ulang dan buat pesanan baru.

Cause: the Lalamove quote expired between validation and payment (SHIPPING_RATE_EXPIRED). Lalamove books with the quote itself, so an expired quote can't be booked. Fix: request a new rate and create a new order straight away.

Courier booking failed

Reason: Order payment successful but failed to get AWB from Courier API: …

Cause: the courier didn't confirm the booking or return an airway bill. The charge has already been refunded to your balance. Fix: create a new order in a few minutes, or choose another courier.

A 201 can still contain a cancelled shipment

If a courier rejects one shipment outright, the order still succeeds, but that shipment comes back with status: "CANCELLED" and its price is refunded. Always check every shipment in the response.

Order cancellation errors

These come from POST /b2b/orders/{orderCode}/cancel.

Order not found

404 · Order with code 'FSO-…' was not found. 403 · You are not allowed to cancel order 'FSO-…'.

Fix: check the order code. You can only cancel orders created with your own API key.

Order has a delivered shipment

400 · Order 'FSO-…' cannot be cancelled because shipment 'SHP-…' is already delivered.

Fix: cancel the remaining shipments one by one with cancelShipment.

Order has no shipments

400 · Order 'FSO-…' has no shipments to cancel.

Fix: nothing to do. The order has nothing to cancel.

Shipment errors

Invalid date range

422 · Invalid startDate filter. · Invalid endDate filter. 422 · startDate cannot be later than endDate.

Cause: the startDate/endDate filter of listShipments or listBalanceLogs can't be read, or the range is reversed. Fix: send ISO 8601 dates, for example 2026-11-01T00:00:00+07:00, with startDate before endDate.

Shipment not found

404 · Shipment with code SHP-… not found. 403 · You are not allowed to view this shipment.

Cause: retrieveShipment was called with an unknown code, or with a shipment that belongs to another account. Fix: use a shipment code (SHP-…) from your own orders.

Not dispatched yet

400 · Shipment 'SHP-…' has not been dispatched yet.

Cause: you tracked a shipment by its code before it has an airway bill (its order wasn't paid or booked). Fix: track only shipments that have an airwayBill. Check the order and its shipment status first.

Tracking code not found

404 · Shipment with code or airway bill '…' not found.

Fix: pass a shipment code (SHP-…) or an airway bill booked through Shipping Engine to trackShipment.

Shipment to cancel not found

404 · Shipment with code 'SHP-…' was not found.

Fix: pass the shipment code (SHP-…), not the airway bill, to cancelShipment.

Cannot cancel a delivered shipment

400 · Shipment 'SHP-…' is delivered and cannot be cancelled.

Fix: nothing to do. Delivered shipments are final. Shipments that are being returned to the sender (RTS_* statuses) can't be cancelled either. Cancelling a shipment that is already CANCELLED succeeds and changes nothing.

Courier refused the cancellation

400 (usually) · the courier's own reason

Cause: once a shipment has an airway bill, Shipping Engine asks the courier to cancel it first. Most couriers refuse after they have picked up the parcel. The shipment stays as it was and nothing is refunded. Fix: let the delivery finish, or contact support. See Cancel a shipment.

Sandbox simulation errors

These come from simulateShipmentStatus.

Simulation in production

403 · Simulate shipment status is not allowed in PRODUCTION environment.

Fix: call this endpoint only in the sandbox, with sandbox credentials. See Sandbox.

Simulation shipment not found

400 · Shipment SHP-… not found. 400 · status must be one of the following values: CANCELLED, DELIVERED, RTS, TRANSIT, DRIVER_ASSIGNED, PRICE_CHANGED, WEIGHT_CHANGED, AIRWAYBILL_UPDATED, RTS_BILLED

Fix: pass the code of a sandbox shipment you created, and one of the listed status values.

Webhook errors

These come from setWebhookEndpoint.

Webhook URL must be HTTPS

400 · Webhook URL must start with https://

Fix: serve your endpoint over HTTPS with a valid certificate and send the full https:// URL.

Webhook secret too short

400 · secret must be longer than or equal to 32 characters 400 · Webhook secret must be at least 32 characters for security.

Fix: generate a random secret of at least 32 characters, for example openssl rand -hex 32, and store it on your server.

Webhook verification failed

422 · The webhook URL could not be verified. The current webhook endpoint stays active and unchanged.

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "The webhook URL could not be verified. The current webhook endpoint stays active and unchanged.",
  "challenge": { "success": false, "statusCode": 404, "responseBody": "Not Found" }
}

Cause: you already have a verified endpoint, and the new URL didn't answer the verification challenge. Your existing endpoint keeps receiving events. Fix: make the new URL reply 2xx with the challenge value, then call setWebhookEndpoint again. See Webhooks.

A first endpoint that fails is saved, but receives nothing

If you have no verified endpoint yet, a failed challenge is not an error: you get 201 with data.challenge.success: false and verificationStatus: "failed". No events are delivered until a later call succeeds. Always check data.challenge.success.

Server errors

Server error

500 · Internal server error 500 · Failed to persist shipping rates. Please try again later.

Fix: retry after a short delay, with exponential backoff. Don't retry createOrder blindly: first check with listShipments whether the order was created. If the error keeps happening, contact support with the time of the request.

Was this page helpful?

On this page