API and Webhook Troubleshooting

Most QrX API and webhook problems come down to authentication, identifiers, rate limits or how your receiver handles webhooks. Check the items below first. The full API reference is at qrx.eu/api.

Authentication Errors (401 or 403)

Protected endpoints need Authorization: Bearer <token>, not the API key. Use the API key (header QrX-MerchantChannel-API-Key) only to call POST /api/v1/auth/token.
Access tokens are valid for one hour. Request a new token when it expires.
Each API key belongs to one merchant channel. A token cannot read or change data of another channel.
Check that the key was not deleted or replaced in PortalX under Settings, Merchant channels.
403 with the code STOCK_SCOPE_MISSING (or the matching code for returns or inbound): the API key is restricted and the part you call is not ticked. Tick it in the block API access of the sales channel and wait 30 seconds. See "Restrict an API Key (API Access)".
403 with the code ACCESS_DENIED on a stock endpoint: QrX warehouse stock is not switched on for the account.

Too Many Requests (429)

Rate limits apply per merchant API key or channel. For example, the token endpoint allows 60 requests per minute and creating transactions allows 300 requests per minute per channel. A 429 response includes Retry-After and RateLimit-Reason headers and the code RATE_LIMIT_EXCEEDED. Wait at least the number of seconds in Retry-After before retrying, and reuse your access token instead of requesting a new one for every call.

Transaction Created but Not Paid Yet

An HTTP 201 on create means QrX accepted the transaction. It is not proof of payment. The payment session with the PSP can be created in the background, and payment happens later at the door. Follow the transaction with webhooks or the status endpoint, and only fulfil or release goods once the transaction is paid. If carrier label creation is requested and fails, the create request itself returns an error.

Other Common Issues

Invalid amount, currency, country, locale or shipping method. Use the reference endpoints to get valid values.
Missing customer email or phone, which are needed for payment links, PIN delivery and support.
Test and live mixed up. Transactions created with testMode: true never create real payments or payouts and must not be treated as real orders.
Retrying a returns command with a new Idempotency-Key. Reuse the same key when retrying the same command; use a new key only for a new command.
Stock corrections: POST /api/v1/stock/adjust without an Idempotency-Key header answers 400 IDEMPOTENCY_KEY_REQUIRED; the same key with a different body answers 409 DUPLICATE_IDEMPOTENCY_KEY; 409 STOCK_CONFLICT means not enough stock, allocated stock or a SKU that matches several items. See "Stock and Warehouse API".

Webhook Checks

Reachable and fast: your endpoint must be publicly reachable over HTTPS and return a 2xx status quickly. Do slow work after responding.
Signature: verify the X-QrX-Signature header. It has the form sha256=<hex>, an HMAC-SHA256 of the raw request body using your webhook signing secret. Compute it over the exact bytes you received, before parsing the JSON.
Rotated secret: after rotating the signing secret, update your receiver or signature checks will fail.
Duplicates: retries and redeliveries can send the same event more than once. Use the X-QrX-Delivery-Id header and the event data to process each event only once.
Event types: the X-QrX-Event header tells you the event. Subscribe only to the events you handle.
Stock events: de-duplicate on eventId and, for stock/adjusted, ignore an event whose sequence is lower than the last one you stored for that item and warehouse. See "Stock and Warehouse Webhooks".

Webhook Health and Delivery Logs

Each webhook subscription in PortalX shows a health status. If an endpoint fails continuously, QrX sends warning emails to the configured recipients and automatically disables the subscription after roughly 24 hours of failure; it can be re-enabled after the endpoint is fixed. Use the delivery log (in PortalX or through the API) to inspect each attempt, including the request, response and retries, and redeliver a failed delivery. You can also send a test webhook to check your receiver.

What to Send Support

Send the environment (test or live), merchant channel, order reference, QrX transaction id, timestamp, endpoint, response status, webhook delivery id and a sanitized request or response body. Remove API keys, access tokens, signatures, secrets, passwords and personal data that is not needed.

When to Contact Our Support Team

Contact QrX support directly for API issues involving leaked credentials, security, production incidents, payment inconsistencies, webhook signature failures you cannot explain, or repeated integration errors. These are always handled by a person. Check status.qr-x.app for current platform status.