Errors
The Helthjem API uses standard HTTP status codes. When a request fails, the response body is a JSON object with a machine-readable errorKey.
Error format
{
"errorKey": "transportSolutionId.required",
"errorMap": {},
"statusCode": 400,
"timestamp": "2026-06-05T12:59:31.131Z",
"path": "/parcels/v1/addresses/find/single"
}
| Field | Description |
|---|---|
errorKey |
Machine-readable error code. Use this in your code, not the HTTP status alone. |
errorMap |
Extra details as key–value pairs. Often empty. |
statusCode |
The HTTP status code. |
timestamp |
When the error occurred, in UTC. |
path |
The request path that caused the error. |
Status codes
| Status | Meaning | Retry? |
|---|---|---|
200 / 201 |
Success. | – |
400 |
The request is invalid, or the action isn't possible (for example, no coverage for an address). | No. Fix the request. |
401 |
The token is missing, invalid or expired. | After requesting a new token. |
403 |
The token is valid but has no access to this shop, shipment or API. | No. |
404 |
The resource wasn't found. | No. |
500 |
Unexpected server error. | Yes, with backoff. See Idempotency & retries. |
No coverage is not an error
When a coverage check or booking returns 400 with errorKey: no.carrier.support (or one of the no.carrier.support.* keys), Helthjem can't deliver with the requested transport solution. This is an expected business outcome. In a checkout, hide that delivery option. Don't retry the same request.
Common error keys
Authentication and access
| Status | errorKey |
Meaning |
|---|---|---|
401 |
authentication.failure |
The token is invalid or expired. |
401 |
authentication.missing |
The Authorization header is missing or malformed. |
403 |
no.access.shop.id |
Your credentials don't have access to this shopId. |
403 |
no.access.api |
Your credentials don't have access to this API. |
Request validation
errorKey |
Meaning |
|---|---|
required.shop.id |
shopId is missing. |
wrong.shop.id |
shopId is not valid. |
transportSolutionId.required |
transportSolutionId is missing. |
invalid.transport.solution |
transportSolutionId is not valid. |
invalid.product.customersystem |
The transport solution isn't set up for this shop. |
party.type.consignee.required |
The booking has no consignee. |
party.type.consignor.required |
The booking has no consignor. |
party.name.required |
A party is missing name. |
party.countryCode.required |
A party is missing countryCode. |
party.zipCode.required |
A party is missing zipCode. |
item.required |
The booking has no items. |
invalid.format.desiredDeliveryDate |
desiredDeliveryDate is not in YYYYMMDD format. |
desiredDeliveryDate.must.be.in.future |
desiredDeliveryDate is in the past. |
desiredDeliveryDate.not.supported |
A date can't be set for this product. |
over.max.length.of.idempotency.key |
The idempotency-key header is longer than 40 characters. |
Coverage and parcel limits
errorKey |
Meaning |
|---|---|
no.carrier.support |
No coverage for this address with the requested transport solution. |
no.carrier.support.package.too.big |
The parcel exceeds the size limit. |
no.carrier.support.package.too.heavy |
The parcel exceeds the weight limit. |
no.carrier.support.package.too.expensive |
The content value exceeds the limit. |
no.carrier.support.order.too.many.parcel.items |
Too many items in the shipment. |
no.carrier.support.admittance.deviation |
The address needs an access key that is missing. |
Duplicates
errorKey |
Meaning |
|---|---|
shipment.id.already.exists |
The shipmentId has already been used. |
tracking.reference.already.exists |
The trackingReference has already been used. |
validation.error.duplicate.order.information |
The booking duplicates an existing order. |
Additional services and articles
errorKey |
Meaning |
|---|---|
invalid.additional.service.specified |
The additional service is not valid. |
additional.service.not.activated.for.shop |
The additional service isn't set up for this shop. |
invalid.value.for.additional.service |
The value for the additional service is not valid. |
article.number.required |
An article number is needed for this additional service. |
invalid.article.quantity |
The article quantity is not valid. |
Cancellation
errorKey |
Meaning |
|---|---|
unable.to.cancel.exported.order.with.status.7 |
The booking has already been handed over for distribution and can't be cancelled. |
order.not.found |
No booking was found for the identifier. |
Server
| Status | errorKey |
Meaning |
|---|---|---|
500 |
internal.error |
Unexpected server error. Retry with backoff. |
Clients must tolerate new error keys being added. Handle unknown keys by their HTTP status code.
Last updated
