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

What to do: for 401, request a new token and retry. For 403, check the shopId and your credentials. Retrying the same request won't help. See Authentication.

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

What to do: fix the field named in the errorKey, then send the corrected request with a new idempotency-key. Don't retry the unchanged request.

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

What to do: don't retry. Offer another delivery option, or check the parcel's weight, size and value against the limits in Delivery methods.

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

What to do: the shipment probably exists already. Treat it as booked, and don't create it again. See Idempotency & retries.

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

What to do: check that the additional service is set up for your shop. Contact integrations@helthjem.no if it should be.

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

Both cancellation errors are returned with status 400, including when no booking is found.

What to do: if the booking has already been handed over, it can't be cancelled through the API. If no booking is found, check that you used the shipmentId (without the (401) prefix), not a tracking reference, and the right environment.

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

What to do: retry with exponential backoff. For bookings, reuse the same idempotency-key.

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.

See also

Last updated