Articles › Troubleshooting, Web Push Notifications

Web Push errors explained (with HTTP status codes)

  • # deliverability
  • # push-api
  • # vapid

When you send a web push notification to a browser push service, you may get an HTTP status code that represents an error.

These are the most common errors that you can get from a browser push service when you send a push message using the Push API / Web Push protocol:

  • 400 Bad Request: the request parameters or headers are invalid and you will need to read the error message returned for more details (e.g. if the message is Unauthorized Registration, then it means that VAPID headers are invalid)
  • 401 Unauthorized, 403 Forbidden: a problem with authentication and cryptography, usually related to VAPID headers (i.e. you need to prove that you are the owner of those subscriptions by including the correct VAPID headers)
  • 404 Not Found: the endpoint (URL) of the push subscription is invalid
  • 410 Gone: the push subscription is expired and no longer exists (e.g. the user has revoked permission for push notifications from browser settings)
  • 413 Payload Too Large: you should reduce the notification size (the maximum payload supported by most browser push services is about 3kB)
  • 429 Too Many Requests: you are above the rate limits allowed by the push service and you should retry later
  • 500 Internal Server Error: the browser push service has a bug or a temporary error occurred.

Needless to say, if the push message was successful, you will get a successful status code (usually 200 OK, 201 Created or 202 Accepted).

You can also find a useful reference for web push errors on the documentation of Mozilla autopush (the push service developed by Mozilla and used by Firefox).

Finally, if you use Pushpad (a service for web push notifications) all the above errors (and many others) are managed automatically by Pushpad and you don't need to worry about them. Thanks to the automatic management of VAPID keys and headers, you will never need to worry about VAPID authentication, which is one of the most common causes of problems. Pushpad also makes automatic retries for all the temporary errors, in order to ensure the notification delivery. It also collects logs, stats and monitoring data about notifications and status codes, increasing the deliverability and making it easy to monitor the successful delivery of notifications.