APNs error codes and how to fix them

Reading an APNs response

Every request to APNs gets an HTTP/2 status. 200 means APNs accepted the notification; it says nothing about whether the device showed it. Anything else comes with a JSON body such as {"reason":"BadDeviceToken"}, and a 410 also carries timestamp, in milliseconds since 1970. Paste the status line and the body together: the explainer above checks that the reason matches the status Apple documents for it, which catches logs where the two came from different requests.

• 200: Success.
• 400: Bad request.
• 403: Error with the certificate or the provider authentication token.
• 404: Invalid :path value.
• 405: Invalid :method value; only POST is supported.
• 410: The device token is no longer active for the topic.
• 413: The notification payload was too large.
• 429: Too many requests for the same device token.
• 500: Internal server error.
• 503: The server is shutting down and unavailable.

Sandbox or production? The usual cause of 400 BadDeviceToken

• A build you run from Xcode is signed with aps-environment = development and its tokens only work on api.sandbox.push.apple.com.
• TestFlight, Ad Hoc and App Store builds use production and api.push.apple.com.
• If one server sends to both, store the environment with each token and choose the host per token. Retrying a mismatched token on the same host fails every time.
• The aps-environment value is in the build's provisioning profile; the .mobileprovision viewer shows it.

Topic errors

DeviceTokenNotForTopic means the token is real but belongs to a different app than the apns-topic you sent: a token from your staging app sent with the production bundle ID, or the widget extension's ID instead of the app's. TopicDisallowed means you may not push to that topic at all, while BadTopic means the topic is malformed. Special push types add a suffix to the topic, for example .push-type.liveactivity or .voip; leaving it out, or adding it to an alert push, is a common cause.

Authentication errors (403)

With token auth, ExpiredProviderToken means the JWT's iat is over an hour old, and InvalidProviderToken means APNs couldn't verify it: a wrong Key ID or Team ID, a revoked key, or a DER-encoded signature. TooManyProviderTokenUpdates (429) means you replace the token too often; keep one for 20 to 60 minutes. The APNs JWT generator builds a known-good token to compare with yours. With certificates, BadCertificate and BadCertificateEnvironment point at the wrong or expired certificate.

410 Unregistered and cleaning your token list

A 410 means the token is no longer active for that topic, typically because the app was deleted. The timestamp tells you when APNs knew that. Delete the token unless the device registered the same token again after that moment. Keep doing this: sending to dead tokens wastes connections. Errors marked as safe to retry (429, 500, 503) deserve backoff with jitter; the others will fail again until you change the request.