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 200 responses 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 `FREE_TIER_JOB_LOCKED` error (Free tier only)

You’re on the Free tier and already have one active job_id for this webhook URL. A different job_id cannot start until the current one ends (or the server-side lock expires; check expiresAt in the error response).

Fix options:

Keep using the same job_id for that pipeline (recommended for one automation = one activity).
End the previous activity for the locked job_id, then start a new job_id:

curl -X POST 'https://YOUR_HOST/notify' \
  -H 'Authorization: Bearer YOUR_UNIQUE_ID' \
  -H 'Content-Type: application/json' \
  -d '{"job_id":"YOUR_CURRENT_JOB_ID","action":"end","message":"done","status":"success"}'

Replace YOUR_CURRENT_JOB_ID with the currentJobId value from the 403 response (or the job you no longer need). After a successful end, you can POST again with a different job_id.

Wait until expiresAt passes, then a new job_id can start without an explicit end (useful if the activity was dismissed and end cannot be delivered).

See also: Free tier: one active pipeline for the rules in plain language.

Getting a 409 `ACTIVITY_ALREADY_RUNNING` error

A Live Activity for this job_id is already running on the device. The server blocks a second start to prevent a duplicate activity appearing on your Lock Screen.

Fix options:

Send updates instead. Omit action (or use action: "update") and the server will update the running activity automatically.
End the current activity first, then start a new one:

curl -X POST 'https://YOUR_HOST/notify' \
  -H 'Authorization: Bearer YOUR_UNIQUE_ID' \
  -H 'Content-Type: application/json' \
  -d '{"job_id":"YOUR_JOB_ID","action":"end","message":"done","status":"success"}'

Wait for expiresAt. The lock expires automatically (typically 8 hours after the last start). Check expiresAt in the 409 response body.

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" or status: "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`	`message` is missing or empty	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_JOB_ID`	`job_id` is missing or empty	Add a non-empty `job_id`
`MISSING_UNIQUE_ID`	Authorization header missing	Add `Authorization: Bearer <your uniqueID>`

Still stuck?

Check the FAQ for answers to common setup and behavior questions, or reach out via Contact.