Developers
API referenceBusiness sign in

Help

Errors

Every error has the same shape, an HTTP status you can branch on and, when there is one, a machine-readable code.

Error body

JSON
{
  "status": "error",
  "message": "This parcel is heavier than Qoene Relay Point allows.",
  "code": "OVER_PRODUCT_WEIGHT_LIMIT",
  "details": {
    "reason": {
      "code": "OVER_PRODUCT_WEIGHT_LIMIT",
      "message": "Relay Point takes parcels up to 20 kg."
    }
  }
}
Error fields
FieldMeaning
messagePlain language. Safe to log; show it to your staff, not necessarily to buyers.
codeOptional machine-readable reason. Branch on it rather than on message.
detailsOptional extra detail, for example reason: { code, message } when a rule refused the request.

Status codes

Status codes
StatusMeaningRetry?SDK error
400The request is not valid: missing or bad field, bad Idempotency-KeyNo, fix itQoeneBadRequestError
401Missing, invalid, expired or revoked keyNoQoeneAuthenticationError
403Missing scope, a LIVE-only call with a TEST key, or an unverified Business ownerNoQoenePermissionError
404Not found for this Business and environmentNoQoeneNotFoundError
409Key reused with another body, reference taken, declaration changed, or state changedNoQoeneConflictError
422A rule refused it: see details.reasonNo, change the requestQoeneUnprocessableError
429Rate limitedYes, after Retry-AfterQoeneRateLimitError
500–504Qoene could not complete itYes, same idempotency keyQoeneServerError
501Not available yetNoQoeneNotAvailableError
No responseNetwork error or timeoutYes, same idempotency keyQoeneConnectionError

Codes you can branch on

Error codes
CodeStatusWhat to do
SENDER_VERIFICATION_REQUIRED403A LIVE booking or ship run needs a verified Business owner. The owner completes sender verification in the Business workspace.
LIVE_KEY_REQUIRED403Labels, manifests, ship runs and webhook endpoints need a LIVE key.
SHIP_PERMISSION_REQUIRED, WALLET_PERMISSION_REQUIRED403The key needs orders.ship or wallet.spend.
PROHIBITED_ITEMS_DECLARATION_REQUIRED400 or 409Send prohibitedItemsDeclaration: { accepted: true, version } with the current version. 409 means it changed: show the new text and confirm again.
COMMERCE_ORDER_CONFLICT409The store already has this external order ID with different details.
PARCEL_DETAILS_MISSING, ORIGIN_POINT_MISSING, ORIGIN_ADDRESS_MISSING422A ship run needs the parcel size and weight, and a drop-off point (Relay) or pickup address (Express) on the run or the store.
ORDER_REFUNDED409The store marked the order refunded, so it is not shipped.
WINDOW_CLOSED, RETURN_OPEN, RETURNS_OFF, NOT_DELIVERED409A return cannot start: the return window closed, one is already open, your policy is off, or the parcel was not delivered yet.
RETURN_REASON_NOT_ALLOWED, RETURN_PRODUCT_NOT_ALLOWED, RETURN_LOCKER_NOT_LIVE422The reason or return option is not in your return policy, or locker drop-off is not live yet.
RETURN_PAID_BY_CUSTOMER409The customer already paid for this return; Qoene support cancels and refunds it.

Refusal reasons

When a quote or booking is refused by a rule, details.reason.code explains it. Examples:

Refusal reasons
ReasonMeaning
OVER_PRODUCT_WEIGHT_LIMIT, OVER_PRODUCT_SIZE_LIMITToo heavy or too large for the product. GET /services lists the limits.
NOT_IN_CONTRACT, PRODUCT_DISABLEDYour contract does not include the product, or it is switched off.
NOT_ACCEPTING_PARCELS, TEMPORARILY_CLOSED, NO_SPACE, OUTSIDE_RELAY_NETWORK …The chosen point cannot take it now; ask the buyer to choose another. See Picking a Qoene Point.

In the SDK

import { QoeneConflictError, QoeneUnprocessableError, QoeneRateLimitError, isQoeneError } from '@qoene/delivery';

try {
  await qoene.shipments.create(booking, { idempotencyKey });
} catch (error) {
  if (error instanceof QoeneUnprocessableError) return askBuyerToChooseAgain(error.reason);
  if (error instanceof QoeneConflictError && error.code === 'PROHIBITED_ITEMS_DECLARATION_REQUIRED') return refreshDeclaration();
  if (error instanceof QoeneRateLimitError) return retryLater(error.retryAfterSeconds);
  if (isQoeneError(error)) logger.error({ status: error.status, code: error.code, requestId: error.requestId }, error.message);
  throw error;
}
curl -i … # the status line and body show the error
try {
    $client->post('shipments', [...]);
} catch (GuzzleHttp\Exception\ClientException $e) {
    $error = json_decode((string) $e->getResponse()->getBody(), true);
    $status = $e->getResponse()->getStatusCode();
    $code = $error['code'] ?? null;
}
response = requests.post(url, headers=headers, json=booking, timeout=30)
if not response.ok:
    error = response.json()
    print(response.status_code, error.get("code"), error["message"])