Troubleshooting
Activity never appears
Checklist, work through these in order:
- Open the app on a physical device first. Island Pulse must run on your iPhone at least once after install to connect to the service. Without this step, webhooks have nowhere to go.
- Allow notifications. iOS Settings → Notifications → Island Pulse → “Allow Notifications” must be on.
- Use iOS 17.2 or later. Earlier versions don’t support this type of Live Activity.
- Use a real device. Island Pulse does not work on the Simulator. If you’re getting
200responses but nothing appears, this is almost certainly the cause. - Re-copy the URL. Copy the webhook URL directly from the Island Pulse home screen. Avoid copying from a notes app or doc where invisible characters might have been added.
- Wait a few seconds after launch. Island Pulse finishes setting up in the background after opening. Give it 5–10 seconds before sending your first webhook.
Getting a 404 DEVICE_NOT_REGISTERED error
Island Pulse has no record for your unique ID. This happens when:
- The app hasn’t been opened yet on the device after install.
- The unique ID in your webhook URL doesn’t match the one currently in the app, re-copy from the home screen.
- You generated a new URL in Settings but haven’t updated your integration yet.
Fix: Open Island Pulse, wait for it to load, then retry.
Getting a 403 TIER_LIMIT_EXCEEDED error
You’re on the Free tier and already have one Live Activity running. A second activity cannot start until the first one ends.
Fix: Either dismiss the first activity (or send action: "end") before starting a new one, or upgrade to Pro for unlimited concurrent activities.
Getting a 502 APNS_PUSH_FAILED error
Island Pulse couldn’t deliver the update to your device. Most common causes:
- Outdated device link, happens after an app reinstall or an iOS upgrade. Open Island Pulse to reconnect, then retry.
- App not installed, Island Pulse has been removed from the device this URL was set up on.
- TestFlight vs App Store, switching between a TestFlight build and an App Store build requires opening the new install and copying a fresh webhook URL.
Activity stuck in “running” state
The activity will stay on screen until:
- You send
action: "end"explicitly, or - You send
status: "success"orstatus: "failed"and the user swipes it away, or - The 8-hour session limit is reached.
status: "success" and status: "failed" change the visual state but don’t auto-dismiss. This is intentional, you should be able to read the result at your own pace.
Updates stop arriving mid-job
- Session expired (8-hour limit). Pro users get automatic session renewal. Free users need to dismiss the activity and start fresh.
- Apple service disruption. Apple’s delivery service very occasionally has incidents. Check Apple’s system status page if updates stop across all jobs at the same time.
JSON validation errors
| Error | Meaning | Fix |
|---|---|---|
Missing primary text | No recognized message field in the payload | Add "message": "your text" |
Invalid status | status value is not running, success, or failed | Fix the value |
Invalid action | action value is not start, update, or end | Fix the value |
MISSING_UNIQUE_ID | No uniqueID resolved | Provide it via Authorization: Bearer …, ?uniqueID=…, ?token=…, or JSON uniqueID |
UNIQUE_ID_MISMATCH | uniqueID set in multiple places with different values | Use only one of Bearer, query, or body, or make them identical |
Still stuck?
Check the FAQ for answers to common setup and behavior questions, or reach out via Contact.