Below is the table of all error codes that any customer endpoint can return. Use the code field for programmatic handling; use the error message for human display.
Some 401 and 503 responses have no body (only HTTP status). These are returned by Insider One's authorization layer.
HTTP | Code | Endpoints | Meaning | Typical Cause | Suggested Fix |
|---|---|---|---|---|---|
400 | VALIDATION_FAILED | All | Generic validation error | A rule failed, no specific code | Read the message, fix the body |
400 | PARTNER_REQUIRED | All | Customer could not be resolved | Your API key is not bound to a defined customer | Check/renew the API key |
400 | REQUEST_INVALID | All | Body empty or unparseable | No JSON sent or JSON malformed | Add/check the JSON body |
400 | ACTIVITY_TYPE_REQUIRED | register / start / update / end | activity_type field missing | Field not sent or empty string | Add the field |
400 | ACTIVITY_ID_REQUIRED | add-users / remove-users / start / update / end | activity_id field missing | Field not sent or empty string | Use the ID from the /register response |
400 | INSIDER_IDS_OUT_OF_RANGE | register / add-users / remove-users | insider_ids not in 1-10,000 range | Empty or more than 10,000 | Narrow the segment size |
400 | ENDS_AT_IN_PAST | register | ends_at in the past | Wrong/old timestamp | Use a future time |
400 | ENDS_AT_TOO_SOON | register | ends_at less than 5 minutes away | Too short | Use a time ≥ 5 minutes in the future |
400 | ENDS_AT_TOO_FAR | register | ends_at more than 7 days away | Maximum exceeded | Use a time ≤ 7 days in the future |
400 | TARGET_DEVICES_INVALID | start / update / end | Empty insider_id or udid in target_devices | Malformed target list | Fill in both for every element |
401 | (no body) | All | Auth failure | Missing, invalid, or unauthorized API key | Renew or authorize the API key |
403 | LIVE_ACTIVITY_DISABLED | All | Product disabled for the customer | Live Activities not active on your account | Request activation from your CSM (requires AOO budget) |
404 | APP_NOT_FOUND | All | Customer not registered in Insider's system | Wrong API key or partner name | Use the correct partner key |
404 | NOT_FOUND | add-users / remove-users / start / update / end | Activity does not exist | Not registered or deleted by /end | Issue a new /register, use the returned ID |
404 | PROFILE_NOT_FOUND | register (single) | Insider has no profile for this insider | Wrong/new insider_id | Verify the ID |
409 | ALREADY_STARTED | add-users / remove-users / start | Activity already started | Second /start call | Call /end and re-register, call /start exactly once |
412 | APNS_CERT_MISSING | All | No APNS certificate for the customer | .p8 not uploaded or iOS push disabled | Upload the .p8 certificate to Insider (coordinate with CSM) |
412 | APNS_CERT_TYPE_UNSUPPORTED | All | Certificate is not .p8 | .p12 etc. uploaded | Switch to a .p8 certificate |
412 | PUSH_TOKEN_NOT_SYNCED | update / end | All target devices have not yet synced the token via the SDK | /update was tried too soon after /start | Wait a few seconds and retry |
422 | NO_ELIGIBLE_DEVICE | register / add-users | No eligible device remained | All insiders filtered out | Check the skipped and gdpr_denied_details in the body, adjust the segment |
429 | (no body) | All | Rate limit exceeded (1000/min) | Too many calls | Apply backoff, retry |
502 | UPSTREAM_UNAVAILABLE | All | Transient error on Insider's side | Temporary service issue | Retry; if it persists, contact Insider |
503 | (no body) | All | Insider authorization layer unreachable | Temporary authorization-layer issue | Retry; if it persists, contact Insider |
Retry strategies
Error class | Safe to retry? | Strategy |
|---|---|---|
400 (validation) | No | Same request must not be retried. Fix the body. |
401 (auth) | No | First renew or authorize the API key, then retry. |
403 LIVE_ACTIVITY_DISABLED | No | Retry is meaningless until the product is activated. |
404 NOT_FOUND | No | Activity is gone or deleted. A fresh register is required. |
409 ALREADY_STARTED | No | /start retries are rejected. /end + re-register |
412 APNS_CERT_* | No | Retry is meaningless until the certificate is fixed. |
412 PUSH_TOKEN_NOT_SYNCED | Yes | Wait a few seconds and retry, it resolves once sync completes. |
422 NO_ELIGIBLE_DEVICE | No | Retry is meaningless unless the segment changes. |
429 (rate limit) | Yes | Exponential backoff (e.g. 1s, 2s, 4s, 8s) |
502 UPSTREAM_UNAVAILABLE | Yes (on idempotent endpoints) | Backoff and retry. Be careful with /start and /end. |
503 (authorization layer) | Yes | Backoff and retry. |
/start retry warning: If you hit a network timeout, the first call may have reached the server and locked the activity. An automatic retry might return 409 ALREADY_STARTED. Do not retry without a status check first.
The same warning applies to /end. If the first call succeeded, the second returns 404.
Error logging recommendation
In your integration, log the following for any troubleshooting needs:
The full HTTP status code
The code and error fields from the response body
The relevant activity_id (if any)
The request timestamp + retry counter