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_keyorserver_rejected, and the model is removed from the device. A refusal the Core could not verify givesserver_rejectedwith 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_closedandcancelled. - 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.