Mobile Subscription Contract

This page is written for mobile client developers. It defines exactly how the API reports an expired subscription and how a client must react.

The stable error code

errorCode = 1001
code      = "SubscriptionExpired"

Mobile responses use the standard envelope:

Detect expiry by the code, never by the text

A client must branch on errorCode == 1001, or equivalently code == "SubscriptionExpired".

A client must not identify expiry from:

• the English errorMessage
• the Arabic errorMessage
• a substring match on either
• an HTTP status code alone
• a redirect target

Message text is localized and can be reworded at any time. The code is the contract.

About the older behaviour

Subscription expiry previously arrived as errorCode 17 on read operations and errorCode 31 on submissions. That is superseded. Expiry now always uses 1001.

17 and 31 were never about subscriptions — they are general-purpose codes still used for their own unrelated meanings, such as an unavailable file or question, a survey that is not assigned to your account, or a failed operation. Keep handling them as you do today; just stop treating them as a signal of expiry.

Operations that can return SubscriptionExpired

Mobile routes keep the envelope at HTTP 200, in line with the rest of the mobile API. The public and viewer link surfaces refuse earlier, at the token layer, and answer 403 directly.

Not gated. Sign-in, the survey list, and reading your own past submissions all keep working while the subscription is expired.

Sign-in and token behaviour

While the subscription is active

Sign-in works normally and returns a JWT.

After the subscription expires

Sign-in still works and still returns a JWT. Authentication and entitlement are separate decisions.

Do not treat a successful sign-in as proof that operations will succeed. The very next protected request can return 1001.

A token issued before expiry

An older, still-valid JWT does not bypass the gate. Subscription state is re-read from the database on every protected request, so the token's age is irrelevant.

A fresh token obtained while expired

Also refused on protected operations. Signing in again is not a workaround. A client that responds to 1001 by re-authenticating will simply receive 1001 again — build a renewal-required state instead of a re-login loop.

After renewal

The same pre-expiry JWT starts working again immediately. None of the following is required merely because the subscription lapsed and was renewed:

• reinstalling or restarting the app
• signing out and back in
• refreshing or replacing the token
• waiting for any cache to expire

Ordinary token expiry is a separate matter. If the JWT itself has passed its own lifetime, normal re-authentication rules apply — but that is unrelated to the subscription.

What a client should do on 1001

1. Map it to a single application state, for example SubscriptionExpired.
2. Show a clear "your organization's subscription needs renewal" message, and point the user at an administrator rather than at a sign-in screen.
3. Stop starting new server-dependent work.
4. Keep all queued offline data. See Mobile Offline Work and Operations.
5. Do not sign the user out.
6. Retry once service is restored — the existing token will work.

Related pages

• Mobile Offline Work and Operations
• What Happens When Your Subscription Expires
• Public and Viewer Links

See also the Mobile & Researcher API section for authentication, survey, submission, and task endpoint details.