Troubleshooting and FAQ

The questions people ask first on the live platform, answered from how the code behaves. Where an answer depends on something not switched on yet, it says so. For what is live today, see Live platform & first steps.

Email, codes and messages

Why didn't I receive an email?

Because no email is being sent yet. The email, SMS and push drivers are set to none: each notification is created and queued, but nothing delivers it. This is deliberate — a queued message goes out once a provider is configured, whereas a pretend sender would report success for messages nobody received. Until then:

In-app notifications work: they appear under the bell on the website and in the apps.
When email is switched on, the backlog is sent. One-time codes in it will have expired; ask for a new one.
Once email is live, a missing message usually means the worker is not running (it is what sends notifications) or the notification was held by the recipient's quiet hours or preferences — see Notifications.

I asked for a sign-in code and nothing arrived

Same cause: email codes and SMS codes are queued, not sent. Use a password instead. On the website choose Sign in with a password instead; if you have no account yet, register with email and password. In the apps, sign in with your password.

I registered, but the verification code never came. Can I use my account?

Yes. Registration creates the account and queues the verification email; the account can sign in with its password while it waits for verification. Wrong passwords still count: after 5 failures in a row the account is locked for 15 minutes (default settings), and the answer is auth.ACCOUNT_LOCKED until then.

A seller invited a staff member, and the invitation never arrived

Staff invitations are sent by email, so they wait in the queue too. The invitation stays valid for 7 days; if it lapses, invite again once email is on.

Shopping and checkout

Why does a product show "Currently unavailable" (out of stock)?

A variant is buyable only while an offer for it has stock available, and available means stock on hand minus stock reserved. Common reasons:

The stock really is zero for that variant — the seller (or an admin) has to add stock.
Other buyers' checkouts are holding the last units. Stock held by an unfinished checkout is released automatically when that checkout expires; the worker checks every minute.
If no seller can offer it at all — offer switched off, seller not active or on vacation — the page says every seller has run out. Other sellers' offers for the same variant are listed below the main offer.

At checkout, the same check runs again: if an item ran out before the order was confirmed you are told so, and nothing is charged.

Why does checkout say sellers can't deliver to my address?

Checkout found no shipping rate that covers the address for at least one seller (error checkout.ADDRESS_UNSERVICEABLE). Shipping today covers Qatar only, nationwide, with Standard and Express methods priced in QAR. So the usual causes are:

The address is outside Qatar — choose or add a Qatar address.
The seller has shipping methods of its own that do not cover the address; a seller's own methods take precedence over the platform's.
A configuration problem: a rate in another currency never applies to a QAR basket. If every address fails for every seller, tell the operator.

You can also remove that seller's items from the cart and check out the rest.

Guests can browse and fill a cart, but placing an order needs a signed-in buyer. Your guest cart is merged into your account when you sign in.

Why can't I pay by card?

Card payment is not configured. Cash on delivery is the only method today. Cash on delivery is not offered for digital goods or above a configured maximum order value. Details in Money, tax & commission.

The driver asks me for a delivery code. Where is it?

The code is sent when the driver requests it at your door. It goes by SMS — not sent yet — and as an in-app notification, so open your notifications on the website or in the buyer app. It is valid for 30 minutes, and only the latest code works.

The mobile apps

The app says it can't connect

Check the connection first: the apps need internet access to reach api.helsen-med.com. The driver app queues some actions offline and replays them later.
Certificate pin. The apps pin the public key of the server's TLS certificate and refuse any connection whose key does not match — this is what stops someone intercepting the traffic. Certificate renewals reuse the same key, so routine renewals do not break the apps. If the key is ever changed, older app builds stop connecting: install the latest APK from the team.
A network that intercepts HTTPS (some corporate or hotel Wi-Fi, inspection proxies) will fail the pin check. Try mobile data.
The apps are not on Google Play yet. Only install APKs the team gave you; Android asks you to allow installing from that source.

SMS codes are not sent yet. Sign in with your password; if your account has none, register on the website with email and password first.

Sellers, dispatch and administrators

An order for an Amr Effendi product is not moving

The five imported sellers have no owner accounts yet, so nobody at those sellers can accept their orders. The worker alerts about orders that miss their acceptance deadline, but it cannot accept for them. The operator has to give each seller an owner first — see the first-day checklist.

Everything I call as an administrator fails with `auth.MFA_REQUIRED`

Administrators must pass a second factor on every request. Without one, only signing in and out, reading your own profile and enrolling are allowed. Enrol with POST /api/v1/auth/mfa/enroll, confirm with POST /api/v1/auth/mfa/confirm, then sign in with password and code. Sellers need a second factor to add a bank account; the seller web walks them through it.

I can't use the delivery web with an administrator account

The delivery web's sign-in asks for email and password only, with no field for an authenticator code, and administrators must pass one. Use a dispatcher account there.

Where is the admin console?

Not deployed publicly yet; that is pending a decision. Administrative actions are made through the API meanwhile, from the Swagger UI — see where the API documentation is.

Why does the API answer "not found" for a record I know exists?

A seller asking for another seller's record gets common.NOT_FOUND, never "forbidden", so the answer does not even confirm the record exists. Check that you are signed in to the right seller.

Product images load slowly or at full size

The image resizing service is not deployed in production, so the original uploads are served. Keep uploaded product images to a sensible size.

API and errors

"Too many requests" (HTTP 429)

Requests are rate-limited per IP address, both at the web server and in the API. Sign-in, registration and code requests have much stricter limits than browsing — for example about ten password sign-in attempts per 15 minutes from one address. Wait and try again; the API's answer carries a Retry-After header saying how long. Many people behind one shared connection (an office network) share one budget. The API's error code is common.RATE_LIMITED.

Where is the API documentation?

The interactive Swagger UI is at api.helsen-med.com/docs; every operation shows who may call it and its rate limit. The API itself is at https://api.helsen-med.com/api/v1. Conventions — errors, money as strings, idempotency keys, cursor pagination — are on API reference.

How do I check the platform is up?

GET /health answers when the API process is up; GET /ready reports ready when the database answers and degraded when it does not. See Deployment & operations.