Respond to the status codes returned by the APNs servers.
Apple Push Notification service (APNs) provides a response to each POST request your server transmits. Each response contains a header with fields indicating the status of the response. If the request was successful, the body of the response is empty. If an error occurred, the body contains a JSON dictionary with additional information about the error.
If you find your device is having trouble receiving notifications, check the common problems listed in Troubleshoot Problems with Receiving Notifications.
Interpret Header Responses
Table 1 describes the meaning of the keys in the header response.
The same value found in the
The HTTP status code.
Table 2 lists the possible values in the
: header of the response.
There was an error with the certificate or with the provider’s authentication token.
The request used an invalid
The device token is no longer active for the topic.
The notification payload was too large.
The server received too many requests for the same device token.
Internal server error.
The server is shutting down and unavailable.
Understand Error Codes
Table 3 lists the keys found in the JSON dictionary for unsuccessful requests. The JSON data might also be included in a
GOAWAY frame when a connection is terminated.
The error code (specified as a string) indicating the reason for the failure. For a list of possible values, see .
The time at which APNs confirmed the token was no longer valid for the topic. This key is included only when the error in the
Table 4 lists the possible error codes included in the reason key of a response’s JSON payload.
The collapse identifier exceeds the maximum allowed size.
The specified device token is invalid. Verify that the request contains a valid token and that the token matches the environment.
The device token doesn’t match the specified topic.
One or more headers are repeated.
The device token isn’t specified in the request
The message payload is empty.
Pushing to this topic is not allowed.
The certificate is invalid.
The client certificate is for the wrong environment.
The provider token is stale and a new token should be generated.
The specified action is not allowed.
The provider token is not valid, or the token signature can't be verified.
No provider certificate was used to connect to APNs, and the
The request contained an invalid
The device token is inactive for the specified topic.
The message payload is too large. For information about the allowed payload size, see Create and Send a POST Request to APNs.
The provider’s authentication token is being updated too often. Update the authentication token no more than once every 20 minutes.
Too many requests were made consecutively to the same device token.
An internal server error occurred.
The service is unavailable.
The APNs server is shutting down.
Listing 1 shows a sample response for a successful push request.
Listing 2 shows a sample response when an error occurs.
Troubleshoot Problems with Receiving Notifications
During testing, if you find that your test devices are not receiving push notifications sent by your provider server, examine the following possible causes:
Make sure that your provider server has an up-to-date device token for your test device. Each time your app launches, it should request its current token and forward that token to your provider server. You should also implement the appropriate failure handler methods to determine if APNs reported an error. See Registering Your App with APNs.
Check for errors returned by APNs. When failures occur, APNs reports an appropriate error back to your provider server. See Handle the Response from APNs.
Make sure you included the apns-push-type key in your request headers. This key is required starting in watchOS 6. The absence of this key may delay the delivery of notifications, or prevent their delivery altogether. See Table 1.
Check to see if you are sending requests to the same device too quickly. APNs queues only one notification at a time for each device, and the device must acknowledge receipt of the notification before APNs dequeues it. If you send multiple notification requests in a very short period of time, each new request might overwrite the previous request.
Check to see if silent notifications are being throttled. APNs sends a limited number of silent notifications—notifications with the
content-availablekey—per day. In addition, if the device has already exceeded its power budget for the day, silent notifications are not sent again until the power budget resets, which happens once a day. These limits are disabled when testing your app from Xcode. See Pushing Background Updates to Your App.
Check the firewall settings of your server and devices. To send notifications, your provider server must allow inbound and outbound TCP packets over port 443 for HTTP/2 connections, or port 2195 when using the binary interface. Devices connecting to APNs over Wi-Fi need to allow inbound and outbound TCP packets over port 5223, falling back to port 443 if port 5223 is unavailable. Computers running macOS must also allow inbound and outbound TCP traffic on port 80.
Verify that you aren't spamming the device. If you send too many notifications to the same device within a short timespan, APNs may treat it as a denial-of-service attack and temporarily block your server from sending notifications.
If your provider server is unable to connect to APNs, examine the following possible causes:
Make sure you have the needed certificates installed on your provider server. If your provider server doesn't have the proper certificates for TLS/SSL validation, it cannot connect to APNs. For certificate-based connections, your provider server must also have the certificate you obtained from Apple. See Establishing a Certificate-Based Connection to APNs.
Check how often your provider server connects to APNs. If your provider server uses the legacy binary interface and opens and closes its connection to APNs repeatedly, APNs may treat it as a denial-of-service attack and temporarily block your server from connecting.
You can verify the TLS handshake between your provider server and APNs by running the OpenSSL
s command from your server, as shown in Listing 3. This command can also show if your TLS/SSL certificates are expired or revoked.