Every response must end in one of four actions
- Accept and record
- Fix the request
- Retry later, with bounds
- Retire the endpoint
Do not retry every failure. A permanent subscription response should remove the endpoint from active sending, while malformed requests and authentication failures require correction before another attempt.
Record the response before interpreting it
For every attempt, store a timestamp, internal message ID, endpoint-record ID, push-service origin, HTTP status, bounded response metadata, attempt number, and next action. Redact the full endpoint and credentials. This creates evidence for support and metrics without turning logs into a subscription-data export.
Use an operational response table
| Response family | Likely meaning | Default action |
|---|---|---|
| 2xx | The push service accepted the request under its protocol behavior. | Record accepted; do not claim the user saw it. |
| 400 or 413 | The request is malformed, missing a required field such as TTL, or too large. | Stop automatic retry; inspect code, headers, encryption, and payload size. |
| 401 or 403 | Sender authorization, VAPID audience, signature, key, or policy failed. | Pause the affected configuration and check the VAPID configuration; repeated sends will not repair it. |
| 404 or 410 | The subscription resource is unknown, expired, or no longer valid under the service’s semantics. | Mark the endpoint inactive and exclude it from future sends. |
| 429 | The service is limiting request volume. | Respect retry guidance when provided and use exponential backoff with jitter. |
| 5xx | The push service encountered a server-side problem. | Retry only while the message remains useful and under a capped attempt policy. |
Actual service behavior and library exceptions must be mapped carefully. Preserve the raw status for diagnosis and use the table as an action model, not as a substitute for the relevant service documentation.
Choose retry from both error type and usefulness
A transient response does not automatically justify retry. Compare the next attempt time with the message TTL and business meaning. A live-event alert may be useless in five minutes; a daily digest may tolerate a later attempt. Never let a queue retry after the information becomes misleading.
Use exponential backoff with random jitter, a maximum attempt count, and a maximum elapsed time. Apply rate limiting at the push-service and tenant levels so one failing campaign cannot consume the entire sender.
Treat TTL as a delivery instruction
Use the dedicated TTL, urgency, and Topic replacement guide to assign those controls from the message's useful lifetime instead of copying one value across campaigns.
RFC 8030 requires a non-negative TTL header in seconds. A zero TTL asks for immediate delivery only when the user agent is available; after that attempt, the message may be removed. A positive TTL defines the requested retention window, but a push service may advertise or use a shorter value. TTL cannot guarantee delivery and should not be presented as a schedule.
Assume an event begins in 20 minutes and the alert is no longer useful at the start. Set a TTL within that remaining usefulness window and cap retries so no attempt can occur afterward. For an account-security event, choose a longer usefulness window but ensure the destination always displays current account state.
Retire permanent failures idempotently
When a response establishes that an endpoint is no longer valid, transition the subscription to an inactive state with the status, timestamp, and reason. Repeating the same transition should be safe. Follow the subscription lifecycle model so it leaves future audiences without erasing the event history needed to explain past attempts.
Do not immediately delete every server record on the first ambiguous network exception. A timeout may leave the request outcome unknown. Separate transport uncertainty from an explicit permanent status.
Use precise delivery language
The same distinction appears in PushNotifications.org's product reporting, which is why an accepted attempt and a visible notification remain separate states.
Call a successful push-service response “accepted” or “submitted successfully.” Reserve “clicked” for a click event and “converted” for a defined downstream action. Unless a platform provides stronger evidence that you actually capture, do not label service acceptance as “seen,” “opened,” or guaranteed device delivery. The push-notification metrics guide carries those definitions into reporting.
Monitor patterns, not only individual errors
- A sudden rise in authentication failures can indicate a VAPID configuration or clock problem.
- A rise in payload errors can indicate a template or serialization change.
- A gradual permanent-failure rate may be normal endpoint churn; an abrupt spike can indicate bad data or a key migration.
- Rate limits concentrated on one service or tenant call for targeted pacing rather than global retries.
Primary protocol references
RFC 8030, Generic Event Delivery Using HTTP Push, defines TTL, payload limits, resource behavior, and protocol responses including rate limiting and expired subscriptions. RFC 8292 covers VAPID authorization, while RFC 8291 covers encrypted payload construction.