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| Field | Meaning |
|---|
message | Plain language. Safe to log; show it to your staff, not necessarily to buyers. |
code | Optional machine-readable reason. Branch on it rather than on message. |
details | Optional extra detail, for example reason: { code, message } when a rule refused the request. |
#Status codes
Status codes| Status | Meaning | Retry? | SDK error |
|---|
400 | The request is not valid: missing or bad field, bad Idempotency-Key | No, fix it | QoeneBadRequestError |
401 | Missing, invalid, expired or revoked key | No | QoeneAuthenticationError |
403 | Missing scope, a LIVE-only call with a TEST key, or an unverified Business owner | No | QoenePermissionError |
404 | Not found for this Business and environment | No | QoeneNotFoundError |
409 | Key reused with another body, reference taken, declaration changed, or state changed | No | QoeneConflictError |
422 | A rule refused it: see details.reason | No, change the request | QoeneUnprocessableError |
429 | Rate limited | Yes, after Retry-After | QoeneRateLimitError |
500–504 | Qoene could not complete it | Yes, same idempotency key | QoeneServerError |
501 | Not available yet | No | QoeneNotAvailableError |
| No response | Network error or timeout | Yes, same idempotency key | QoeneConnectionError |
#Codes you can branch on
Error codes| Code | Status | What to do |
|---|
SENDER_VERIFICATION_REQUIRED | 403 | A LIVE booking or ship run needs a verified Business owner. The owner completes sender verification in the Business workspace. |
LIVE_KEY_REQUIRED | 403 | Labels, manifests, ship runs and webhook endpoints need a LIVE key. |
SHIP_PERMISSION_REQUIRED, WALLET_PERMISSION_REQUIRED | 403 | The key needs orders.ship or wallet.spend. |
PROHIBITED_ITEMS_DECLARATION_REQUIRED | 400 or 409 | Send prohibitedItemsDeclaration: { accepted: true, version } with the current version. 409 means it changed: show the new text and confirm again. |
COMMERCE_ORDER_CONFLICT | 409 | The store already has this external order ID with different details. |
PARCEL_DETAILS_MISSING, ORIGIN_POINT_MISSING, ORIGIN_ADDRESS_MISSING | 422 | A 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_REFUNDED | 409 | The store marked the order refunded, so it is not shipped. |
WINDOW_CLOSED, RETURN_OPEN, RETURNS_OFF, NOT_DELIVERED | 409 | A 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_LIVE | 422 | The reason or return option is not in your return policy, or locker drop-off is not live yet. |
RETURN_PAID_BY_CUSTOMER | 409 | The 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| Reason | Meaning |
|---|
OVER_PRODUCT_WEIGHT_LIMIT, OVER_PRODUCT_SIZE_LIMIT | Too heavy or too large for the product. GET /services lists the limits. |
NOT_IN_CONTRACT, PRODUCT_DISABLED | Your 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"])