WebhooksWorkers
Outage Codes
The outage_code and outage_category values in outage webhooks, and how to detect permission revocation.
The data.outage_code field on every outage_started and outage_ended webhook is a machine-readable identifier of the outage reason.
The accompanying data.outage_category groups codes by what's responsible:
outage_category | What it means |
|---|---|
behavioural | Caused by worker action (denied permission, force-stopped app, airplane mode). |
os | Caused by the operating system (kill, suspend, crash). |
adversarial | Anti-fraud signal (mocked location, time tampering). |
sporadic | Transient hardware/environment issue (GPS unavailable). |
reachability | Server-side cannot reach the device (push failed, no token). |
outage_code | outage_label | outage_category | Description |
|---|---|---|---|
location_permissions_denied | Location permission denied | behavioural | Worker fully denied location permission. |
location_permission_when_in_use_background | Background location permission not granted | behavioural | Worker granted "When In Use" only — app cannot start tracking from background. |
location_permission_imprecise | Location imprecise | behavioural | Worker downgraded to approximate location instead of precise. |
location_permission_not_determined | Location permission unknown | behavioural | Permission state is unset (e.g. "Allow Once" reset, or never prompted). |
location_permission_restricted | Location permission restricted | behavioural | Permission blocked by Screen Time, parental controls, or MDM policy. |
location_services_disabled | Location services disabled | behavioural | Phone-level Location Services toggle is off. |
location_unavailable | Location unavailable | sporadic | App could not get a fresh GPS fix (signal lost, indoors, airplane mode, etc.). |
location_unavailable_provisional_authorization | Location unavailable auth | reachability | App requested Always permission without first asking When In Use; iOS limits authorization. |
location_mocked | Location mocked | adversarial | A mock-location app was active on the device. |
airplane_mode_detected | Device in airplane mode | behavioural | Worker enabled airplane mode. |
notifications_permission_denied | Notification permission denied | behavioural | Notifications disabled — push-driven start cannot be delivered. |
foreground_service_denied | Foreground service start prohibited | behavioural | Android battery optimizations declined the wake-up push (foreground service start blocked). |
tracking_service_terminated | Tracking service terminated | behavioural | App was force-stopped by worker or killed by OS battery management. |
sdk_killed_by_user | App killed by user | behavioural | Worker swiped the app away or used "Clear all". |
sdk_killed_permission_change | App killed by permission change | behavioural | Worker revoked a permission mid-tracking and the OS killed the app. |
sdk_killed_low_memory | Low memory | os | OS killed the app to reclaim memory. |
sdk_killed_crashed | App crashed | os | App crashed unexpectedly. |
sdk_killed_excessive_resource_usage | App killed — excessive resource usage | os | OS killed the app for using too much CPU, battery, or memory. |
sdk_killed_app_not_responsive | App killed for being unresponsive | os | OS killed the app because it stopped responding (ANR-style). |
sdk_killed_suspended | App suspended | os | OS suspended app execution while device was idle or locked. |
storage_unavailable | Storage unavailable | behavioural | Device storage is full; app cannot persist or send tracking data. |
push_notification_failed | Push notification failed | reachability | Server sent a push to start tracking but it didn't reach the device. |
push_token_missing_to_start_tracking | Push token missing | reachability | Push notification service didn't supply a messaging token to the app. |
Detecting permission revocation
To detect when a worker no longer has location permission to track, watch for an outage_started webhook where data.outage_category is behavioural and data.outage_code is one of:
location_permissions_deniedlocation_permission_when_in_use_backgroundlocation_permission_impreciselocation_permission_not_determinedlocation_permission_restrictedlocation_services_disabledforeground_service_denied(Android)sdk_killed_permission_change(Android)
Track the matching outage_ended event with the same outage_code to know when the worker has resolved the issue.