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
| Status | Meaning | Retry? |
|---|---|---|
400 | The request is invalid. Fix it before retrying. | No |
401 | The token is missing, expired or invalid. | After getting a new token |
403 | Your API key's role lacks a permission, or the resource isn't yours. | No. Ask your admin. |
404 | Nothing was found, for example no courier serves the route. | No |
422 | The request is valid but not allowed in the current state. | No |
500 | Something went wrong on our side. | Yes, with backoff |
At a glance
| Area | Status | Message (starts with) | Entry |
|---|---|---|---|
| Auth | 401 | Missing authorization header, Invalid authorization scheme | Token problems |
| Auth | 401 | "exp" claim timestamp check failed, signature verification failed | Token rejected |
| Auth | 401 | OAuth client is not registered in the app … | Client not registered |
| Auth | 401 | Organization owner is not … | Organisation owner missing |
| Auth | 403 | You're not authorized to access this resource (Missing permissions: …) | Missing permission |
| Validation | 400 | list of field messages | Validation errors |
| Regions | 400 | Query parameter '…' is required. / must be a valid number. | Region parameter missing |
| Regions | 400 | Field 'keyword' is required. | Search keyword missing |
| Regions | 400 | Query parameter 'postCode' is required. | Postcode missing |
| Couriers | 400 | "courier_code" is not allowed to be empty, Invalid courier_code '…'. | Courier code invalid |
| Couriers | 400 | Invalid courier type. …, Invalid isEnabled value. … | Courier filter invalid |
| Rates | 400 | insurance parameter is required … | Insurance is required |
| Rates | 400 | packages.0.itemValue must not be less than 15000 | Item value too low |
| Rates | 400 | vehicle should not be empty | Vehicle missing |
| Rates | 400 | stopOrder is required …, stopOrder must be unique … | Destinations need a stop order |
| Rates | 400 | Courier adapter for … was not found. | Unknown courier |
| Rates | 400 | Selected courier service does not support insurance … | Insurance not supported |
| Rates | 400 | Custom COD amount cannot be less than … | Custom COD too low |
| Rates | 400 | COD amount (Rp …) exceeds the maximum COD … | COD above the courier's limit |
| Rates | 403 | You are not allowed to use COD for shipping rate COD. | Missing COD permission |
| Rates | 404 | No shipping rates available … | No rates available |
| Rates | 404 | Shipping rate with code '…' not found or unavailable | Rate not found |
| Orders | 400 | Invalid shipping rate code provided. | Invalid rate code |
| Orders | 400 | Shipping rate code '…' have expired. | Rate expired |
| Orders | 400 | Courier service '…' is currently not available. | Service unavailable |
| Orders | 400 | … is disabled for one or more package categories. | Package category not allowed |
| Orders | 400 | Total package weight …, Package dimensions exceed … | Vehicle capacity exceeded |
| Orders | 400 | All shipments in one order must be either COD or non-COD. | COD and non-COD mixed |
| Orders | 400 | Courier service '…' (…) does not support COD. | COD not supported |
| Orders | 403 | You are not allowed to use COD for COD orders. | COD not allowed |
| Orders | 400 | … does not support pickup. / … does not support dropoff. | Fulfilment method not supported |
| Orders | 400 | Pickup shipments require sender coordinates. | Sender coordinates required |
| Orders | 400 | code: PICKUP_SCHEDULE_EXPIRED | Pickup schedule too soon |
| Orders | 400 | code: PICKUP_SCHEDULE_NOT_QUOTED | Pickup schedule not quoted |
| Orders | 400 | shippingOptions.schedule must be a valid ISO 8601 datetime. | Invalid pickup schedule |
| Orders | 400 | Receiver details are missing for shipping rate destinations. | Receiver details missing |
| Orders | 400 | Payment failed, but order '…' was created successfully. Reason: … | Payment failed |
| Cancel order | 404 / 403 | Order with code '…' was not found. / You are not allowed to cancel order '…'. | Order not found |
| Cancel order | 400 | Order '…' cannot be cancelled because shipment '…' is already delivered. | Order has a delivered shipment |
| Cancel order | 400 | Order '…' has no shipments to cancel. | Order has no shipments |
| Shipments | 422 | Invalid startDate filter., startDate cannot be later than endDate. | Invalid date range |
| Shipments | 404 / 403 | Shipment with code … not found. / You are not allowed to view this shipment. | Shipment not found |
| Shipments | 400 | Shipment '…' has not been dispatched yet. | Not dispatched yet |
| Shipments | 404 | Shipment with code or airway bill '…' not found. | Tracking code not found |
| Shipments | 400 | Shipment '…' is delivered and cannot be cancelled. | Cannot cancel a delivered shipment |
| Shipments | varies | the courier's reason | Courier refused the cancellation |
| Sandbox | 403 | Simulate shipment status is not allowed in PRODUCTION environment. | Simulation in production |
| Sandbox | 400 | Shipment … not found. | Simulation shipment not found |
| Webhooks | 400 | Webhook URL must start with https:// | Webhook URL must be HTTPS |
| Webhooks | 400 | secret must be longer than or equal to 32 characters | Webhook secret too short |
| Webhooks | 422 | The webhook URL could not be verified. … | Webhook verification failed |
| Server | 500 | Internal server error | Server 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?