Errors in 4.0

The error codes an app gets from SDK 4.0, what each one means now, and the report every failure sends to Quran Lab.

SDK 4.0 keeps the error codes of 3.x: the same catalogue, each code with its message, what to do, and its place on the errors page. Two things are new. Each code now means one thing, so your app can act on it. And every failure a learner can hit is reported to Quran Lab and shown on your app's Problems tab.

The code your app gets

What happened The code
A request the call cannot go without got no answer at all (offline, a name that does not resolve, a refused connection; on the web, Quran Lab's frame answering on neither host within 20 seconds) needs_connection
A server answered with a failure: a server error, a "too many requests" answer, a redirect, or an answer that is not what was asked download_failed, whose message names the answer, for example "the server answered 503"
The signed config does not verify, has expired or cannot be read, and no stored one can stand in download_failed, naming that
Quran Lab refused the key or the app invalid_key, or server_rejected with the reason
The SDK is older than the oldest one Quran Lab still serves sdk_too_old
The browser or device lacks something the SDK needs, such as WebAssembly, its SIMD or WebCrypto runtime_unsupported, naming it
Not enough memory to start the engine or open the model, or an engine file that does not load engine_failed
The device's storage is full, or fails in another way storage_full, or storage_failed
A downloaded file is not the file that was published, or the model's manifest does not verify checksum_mismatch, or signature_invalid

So needs_connection is never the answer of a server. When your app gets it, the device could not reach Quran Lab: ask the learner to connect, then try again. For download_failed the fix is to try again later; a download resumes where it stopped.

The lease

Opening the model in 4.0 needs a valid lease (Offline use and the lease).

  • With no valid lease, outside its grace, and no answer to the lease request: needs_connection.
  • On the lease request only a stop that the Core verified counts as a stop. It gives invalid_key or server_rejected, and the model is removed from the device. A refusal the Core could not verify gives server_rejected with the server's reason, and removes nothing.
  • An open in the grace is no failure. Your app is not told, and the SDK sends a silent report.
  • On the web, a lease given without a clear answer of the invisible bot check is no failure either: the learner gets a lease all the same, the next lease checks again, and the frame sends a silent report.

What is reported

  • Every error your app receives, except the five that only say the app used the API wrongly: invalid_argument, client_exists, session_open, session_closed and cancelled.
  • The failures the SDK goes on from without telling your app: storage that could not be opened, model files the system removed, the web engine running on the page's own thread, a launch whose config, registration, attestation or lease request failed with an answer, an open in the lease's grace, a web lease given without a clear answer of the bot check, an analytics report that was refused, a shared recording that will not be uploaded. These show as silent on the Problems tab.
  • A device that is simply offline in the background is normal, and is not reported on its own.

What a report holds

Where it failed and why, the code your app got, the HTTP status, the name and code of the platform's error, how many times it happened that day, whether the SDK tried again, whether it was the install's first launch, and the SDK, app and model versions. Then what the device could do. On the web: the browser and its major version, the system, and capabilities such as WebAssembly SIMD and threads, cross-origin isolation, WebCrypto and storage. On a phone or a desktop: the device's model code, its memory and free space in broad steps, and whether the process is 32 or 64 bit.

Never in a report: audio, what the model heard, a name, an identifier of the install, the device, the learner or advertising, an IP address, an address or a file path, the browser's identification string, a location, or the error's message.

How often

One report per install, day and failure, with how many times it happened. At most 16 different failures per install a day. Reports are sent with the SDK's analytics, and 30 seconds after a new one while the app is in front. There is no option for them in your app. Reports from a development key are kept apart from production.

The C and Apple SDKs report from 4.0 on. The newest 3.x patches for the web and Android send the same reports.