DEV Community: Espresso Notify

Why your push notification didn't arrive: the FCM and APNs errors, and the failures nobody reports

Espresso Notify — Thu, 29 Oct 2026 21:20:28 +0000

A push notification has two lives. In the first, your server asks Firebase Cloud Messaging (FCM) or Apple's APNs to deliver it, and gets an answer. In the second, a phone somewhere decides whether to show it. Most debugging goes wrong because people read the first answer as if it described the second.

This is a guide to both: what the errors from FCM (HTTP v1) and APNs mean, which ones to retry, which ones to treat as "delete this token", and the failures that come back with no error at all.

"Accepted" is not "delivered"

When APNs answers 200, it accepted your request. When FCM answers with a message name, it accepted your request. A web push service answering 201 Created is the same: RFC 8030 says the message "was accepted", nothing more.

Apple's documentation does not give the sending server a signal that the notification was displayed. FCM is more generous but still separates the two: in its BigQuery export, MESSAGE_ACCEPTED means the FCM server received a valid request, while MESSAGE_DELIVERED means it reached the FCM SDK on the device, and that field is not exported by default. FCM's delivery reports also depend on Google Analytics and can lag by up to 24 hours.

For your pipeline: store "accepted by provider" and "delivered/opened" as different facts. Accepted comes from the provider's answer. Delivered and opened have to come from your app reporting back.

Sort every error into one of four buckets

Before the table, a rule that saves hours. Every provider error is one of these:

The token is dead. Delete it and never send to it again.
Your request is wrong. Fix it; retrying the same request repeats the failure.
Your credentials or configuration are wrong. Fix the setup; it affects many devices at once.
The provider is struggling or you are going too fast. Retry later, with exponential backoff and jitter.

Mixing the buckets is how teams end up deleting healthy tokens during an outage, or retrying a dead token forever.

FCM (HTTP v1)

Error	HTTP	What it means	What to do
`UNREGISTERED`	404	The token is no longer valid: the app was uninstalled, unregistered, or the token expired	Delete the token
`INVALID_ARGUMENT`	400	A parameter is invalid: a malformed token, wrong package name, message too big, reserved data key, invalid TTL	Read the `BadRequest` detail. Fix the message. Delete the token only after confirming the payload is valid
`SENDER_ID_MISMATCH`	403	The sender you authenticated as is not the sender the token was registered for	Check that your service account belongs to the same Firebase project as the app. Do not delete tokens first
`QUOTA_EXCEEDED`	429	Rate exceeded for the project, one device, or one topic	Reduce the rate. FCM recommends exponential backoff with an initial delay of at least 1 minute for message and topic rates
`UNAVAILABLE`	503	FCM is overloaded	Retry the same request, honor `Retry-After` if present, back off exponentially, add jitter
`INTERNAL`	500	Unknown FCM error	Retry with backoff; check the FCM status dashboard; if it persists, contact Firebase support
`THIRD_PARTY_AUTH_ERROR`	401	The APNs certificate or web push auth key is invalid or missing, for a message to an iOS device or a web registration	Fix the APNs or web push credentials in the Firebase console

Three details from the official docs that are easy to miss:

INVALID_ARGUMENT is the ambiguous one. FCM's own token guide says it can mean an invalid registration or a bad payload, and tells you to treat it as a dead token only when you have confirmed the payload is fine. Log the field detail before you delete anything.
The size limit is 4096 bytes for most messages and 2048 bytes for messages to topics, keys and values included. TTL must be an integer between 0 and 2,419,200 seconds (4 weeks).
On Android, FCM expires a registration after 270 days of inactivity. On iOS it relies on APNs, which has no such expiry, so Firebase recommends you prune stale tokens yourself.

APNs

Status	`reason`	What it means	What to do
400	`BadDeviceToken`	The token is invalid, or does not match the environment	First check sandbox vs production. Only then treat it as dead
400	`DeviceTokenNotForTopic`	The token does not belong to the topic (bundle ID) you sent	Fix the `apns-topic`. Apple lists it among the errors not to retry as-is
400	`TopicDisallowed`	Pushing to this topic is not allowed	Check that the topic is allowed for your app and key
403	`ExpiredProviderToken`	Your JWT is stale	Generate a new one and retry
403	`InvalidProviderToken`	The JWT is invalid or its signature can't be verified	Check the key, Key ID and Team ID
410	`Unregistered`	The token is no longer active for the topic; the response includes a `timestamp`	Stop sending to it
413	`PayloadTooLarge`	The payload is over the limit	Shrink it. 4 KB (4096 bytes), 5 KB for VoIP
429	`TooManyRequests`	Too many requests to the same device token	Retry with a delay
429	`TooManyProviderTokenUpdates`	You refresh your JWT too often	Refresh at most once every 20 minutes
500 / 503	`InternalServerError`, `ServiceUnavailable`, `Shutdown`	Apple-side trouble	Retry with backoff

The rules in Apple's own words are worth keeping near your code: don't retry BadDeviceToken, DeviceTokenNotForTopic, Forbidden, ExpiredToken, Unregistered or PayloadTooLarge; you can retry TooManyRequests with a delay; 5xx responses can be retried, and Apple mentions waiting 15 minutes and using back-off.

Two more things from that page. Errors in the 4xx range slow you down: APNs can disconnect a provider connection that produces too many of them, and sooner for BadDeviceToken. Sending to dead tokens is not only wasteful, it throttles your good traffic. And BadDeviceToken has a classic cause: a token from an Xcode (development) build belongs to the sandbox environment, while TestFlight and App Store builds belong to production. Send to the wrong host and every token of the other kind fails.

For your pipeline: map each code to a bucket in one place (a lookup table, not scattered ifs), and log the raw code next to your own classification. When a new reason shows up, the default should be "don't delete, don't retry blindly, alert".

Failures that come back without an error

This is the part the tables can't help with. The provider said yes, and the user saw nothing.

Notifications are off for the app. On Android 13 and later, notifications are off by default for a new install, and if the user taps Don't allow, all notification channels are blocked. The token stays valid and the send keeps being accepted. FCM even warns that high-priority messages that produce no visible notification can be deprioritized over a 7-day window. Check areNotificationsEnabled() in the app and report it to your server along with the token. Do Not Disturb and Focus modes work the same way from your server's point of view: the system decides what to show, and nothing tells you.

Doze and priority. FCM's normal-priority messages may be held back while the device is in Doze; high priority is the option meant for urgent, user-visible content. APNs has the same idea: apns-priority 10 means now, 5 means "when power considerations allow", and 5 or 1 can be grouped into bursts or throttled. Pick the priority per message type, not one global default.

Expiry while the phone is offline. With no TTL, FCM can keep a message for up to four weeks; with a TTL of 0 it discards what it can't deliver immediately. APNs with apns-expiration: 0 tries once and doesn't store the notification. If your "flash sale ends in 1 hour" push sat in a queue for a day, it should have expired, so set TTL on purpose.

Android vendors that kill apps. Some manufacturers aggressively stop background apps to save battery. The community site dontkillmyapp.com rates Xiaomi, Samsung, OnePlus and Huawei at its worst level. You can't fix this from the server, but you can detect the pattern: if your delivery stats look fine overall and bad for one device brand, this is the first suspect. Link users to the vendor-specific steps from your support page.

Expo Go. If you test with Expo Go, remote push is not available there on Android from SDK 53; Expo says a development build is required, while local notifications still work in Expo Go. "It works in my build and not in Expo Go" is expected behavior.

Web push. Three things trip people up. On iOS the permission request must come from direct user interaction, and asking from a button is the safe default everywhere. The push needs a registered service worker. And on iOS and iPadOS 16.4 and later, web push works for web apps added to the Home Screen, not for a plain Safari tab. When a subscription has expired, RFC 8030 says the push service answers 404: delete it.

A debugging order that works

Did the provider accept the request? Read the status and reason/error code, not just "success".
Is the token alive? Check how old it is and when the app last registered it.
Right environment? Sandbox vs production for APNs, right Firebase project for FCM.
Is the payload under the limit, with a sensible TTL and priority?
Is the app allowed to show notifications on that device (permission, channel, focus modes)?
Is the device a known battery-killer, or a build that can't receive remote push (Expo Go)?
If you control the app, did it report receipt? If not, you are guessing.

About the project

I work on Espresso Notify, a push notification service for iOS, Android and web with a dashboard and a REST API, and the cases above shaped how it reports a failure. Each failed device gets a stable code and what to do about it instead of a bare provider string, tokens the provider says are dead are removed so the next send skips them, and the docs state plainly that "sent" means the provider accepted it. It is free up to 10,000 devices.

How delivery results are reported: https://docs.espressonotify.com/docs/sending/verify-delivery
Setting up the iOS key, including the sandbox/production choice: https://docs.espressonotify.com/docs/credentials/apns

A question for the comments: when FCM returns INVALID_ARGUMENT, how do you decide between "bad payload" and "dead token" in your pipeline? Do you parse the BadRequest detail, or do you wait for a second failure?

Retries without duplicate sends: idempotency keys, atomic transitions and the double click

Espresso Notify — Thu, 29 Oct 2026 21:19:58 +0000

You send a request that triggers an e-mail, a push notification, an SMS or a payment. The connection drops. You do not know whether the server received it. Do you send it again?

If you retry, you may send the message twice. If you don't, you may send it zero times. Over a network, the honest answer is that you must retry, so the real work is making a repeat harmless. This article covers the four places where duplicates come from and the pattern that closes each one: the HTTP boundary, the queue, the state change and the button.

Why retrying is not optional

A request can fail in three ways that look identical to the client: the request never arrived, it arrived and failed, or it arrived and succeeded but the response was lost. The client sees a timeout in all three. If your API sends something irreversible, "just retry" is a bug waiting for the third case, and "never retry" is an outage waiting for the first.

The fix is not smarter retries. It is making the operation idempotent: doing it twice has the same effect as doing it once.

1. Idempotency keys at the HTTP boundary

The contract has four rules:

The client generates the key, before the first attempt, and sends the same key on every retry.
The server stores the first result next to the key and replays it for later calls with the same key.
Same key, same body: replay. Do not run the effect again.
Same key, different body: error. The client has a bug (it reused a key for a new intent) and silently replaying the old result would hide it. A 422 makes it loud.

The key should name the event, not the attempt: order-1042-shipped is good, a fresh UUID generated inside the retry loop protects nothing. If there is no natural event id, generate a UUID once per user intent and keep it until the call succeeds.

On the server, the unique constraint does the hard part. Two identical requests arriving at the same moment cannot both insert the same key:

CREATE TABLE idempotency_keys (
  project_id   bigint      NOT NULL,
  key          text        NOT NULL,
  request_hash text        NOT NULL,
  message_id   bigint,
  created_at   timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (project_id, key)
);

Scope the key to a tenant (here project_id), so two customers choosing welcome-1 don't collide. Hash a canonical form of the body (sorted keys, no whitespace) so equivalent JSON compares equal.

The handler claims the key and creates the effect in the same transaction:

async function acceptSend(tx: Tx, projectId: number, key: string, body: SendBody) {
  const hash = sha256(canonicalJson(body));

  const claimed = await tx.query(
    `INSERT INTO idempotency_keys (project_id, key, request_hash)
     VALUES ($1, $2, $3)
     ON CONFLICT (project_id, key) DO NOTHING`,
    [projectId, key, hash],
  );

  if (claimed.rowCount === 0) {
    const { rows } = await tx.query(
      `SELECT request_hash, message_id FROM idempotency_keys
       WHERE project_id = $1 AND key = $2`,
      [projectId, key],
    );
    if (rows[0].request_hash !== hash) {
      throw new HttpError(422, 'idempotency_key_reused');
    }
    return { status: 'duplicate_ignored', id: rows[0].message_id }; // 202
  }

  const { rows } = await tx.query(
    `INSERT INTO messages (project_id, payload, status)
     VALUES ($1, $2, 'queued') RETURNING id`,
    [projectId, body],
  );
  await tx.query(
    `UPDATE idempotency_keys SET message_id = $3
     WHERE project_id = $1 AND key = $2`,
    [projectId, key, rows[0].id],
  );
  return { status: 'queued', id: rows[0].id }; // 202
}

Under READ COMMITTED, a concurrent request with the same key waits on the unique index until the first transaction commits, then takes the conflict branch and reads the committed row. Because the key and the message commit together, there is no state where the key exists and the message doesn't.

Two details worth deciding on purpose:

Don't consume the key on a refused request. If validation fails with a 400, store nothing, so the client can fix the body and reuse the key.
The effect is a row, not a call. The handler enqueues the work; a worker sends it later. Calling the provider inside the request would put a network call between "claimed" and "committed".

Takeaway: a key without a unique constraint is a suggestion. Make the database refuse the second insert.

2. The client: retry only what can succeed later

The client half is a loop that generates the key once and retries only answers where the same request might succeed:

const RETRYABLE = new Set([429, 500, 502, 503, 504]);
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
const backoff = (i: number) => Math.random() * Math.min(30_000, 500 * 2 ** i);

async function postOnce(url: string, body: unknown, key: string, attempts = 5) {
  for (let i = 0; i < attempts; i++) {
    try {
      const res = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'Idempotency-Key': key },
        body: JSON.stringify(body),
      });
      if (res.ok) return res.json();
      if (!RETRYABLE.has(res.status)) throw new ApiError(res.status, await res.json());
      const retryAfter = Number(res.headers.get('Retry-After'));
      await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(i));
    } catch (err) {
      if (err instanceof ApiError) throw err; // a 4xx will not change on retry
      await sleep(backoff(i)); // no answer at all: same key, try again
    }
  }
  throw new Error('gave up after retries');
}

// Called once per intent, not once per attempt:
postOnce('/v1/messages', body, `order-${order.id}-shipped`);

The rules behind it: retry 429 and 5xx with growing, randomized waits; honor Retry-After when present; retry a timeout with the same key; never retry a 400, 401, 403, 404 or 422, because the answer will be the same. Add jitter, or a thousand clients that failed together will retry together.

3. At-least-once queues need idempotent consumers

Most queues promise at-least-once delivery. A worker that crashes after doing the work but before acknowledging it gets the same message again. That's a feature, but it means the consumer has to be idempotent too.

When the effect is in your own database, put the dedupe record in the same transaction:

BEGIN;
INSERT INTO processed_messages (consumer, message_id)
VALUES ('mailer', $1)
ON CONFLICT DO NOTHING;
-- if 0 rows were inserted: ROLLBACK and acknowledge, already done
-- otherwise: apply the effect, then COMMIT

When the effect lives outside (an e-mail provider, a push service), you can't share a transaction. Two options: pass the provider a key if it supports one, and record "sent" with the provider's id as soon as you get it. For push specifically there is also a safety net: APNs lets you set apns-collapse-id to merge notifications into one, and FCM's collapse key replaces a pending message with the same key for the same token. These don't replace idempotency, since they only help while the earlier message is still waiting, but they limit the damage of a duplicate.

Takeaway: assume every message arrives twice and write the consumer so that's boring.

4. Atomic state transitions: approvals and refunds

Some duplicates have nothing to do with the network. Two admins click Approve on the same refund. A webhook is delivered twice. The naive code reads the status, checks it, then writes:

const refund = await getRefund(id);
if (refund.status === 'pending') {   // two requests can both pass this check
  await approve(id);
  await payOut(refund);
}

Fix it with a compare-and-set: let the database check and change the status in one statement, and use the number of affected rows as the verdict.

const res = await tx.query(
  `UPDATE refunds
      SET status = 'approved', approved_by = $2, approved_at = now()
    WHERE id = $1 AND status = 'pending'`,
  [id, adminId],
);

if (res.rowCount === 1) {
  await tx.query(`INSERT INTO payouts (refund_id) VALUES ($1)`, [id]); // we won: do the effect
} else {
  const { rows } = await tx.query(`SELECT status FROM refunds WHERE id = $1`, [id]);
  if (rows[0].status !== 'approved') throw new HttpError(409, 'refund_not_pending');
  // already approved by someone else: report success, do nothing
}

Exactly one caller sees rowCount === 1. The loser gets a clear answer, and doing the payout in the same transaction means it can't be skipped or doubled. If you prefer ORM-style updates, a version column checked in the WHERE gives the same guarantee.

Takeaway: don't check state in application code and write in another statement. Put the expected state in the WHERE.

5. The UI: a button that can only be pressed once

Most duplicates start with a human. Double click, slow network, impatient second tap. Three layers, cheapest first:

Disable the button while the request is pending.
Don't let the framework retry mutations behind your back. In TanStack Query, mutations are not retried on error by default, but set retry: false explicitly so a global default change doesn't silently turn a POST into a repeat.
Create the key once per intent, so even a double click that slips through sends the same key twice.

function ShipButton({ order }: { order: Order }) {
  const key = useRef(crypto.randomUUID()); // one key per intent
  const ship = useMutation({
    mutationFn: () => api.ship(order.id, key.current),
    retry: false,
    onSuccess: () => { key.current = crypto.randomUUID(); },
  });

  return (
    <button
      disabled={ship.isPending}
      onClick={() => { if (!ship.isPending) ship.mutate(); }}
    >
      Mark as shipped
    </button>
  );
}

disabled only updates after a render, so two clicks can land in the same frame; the isPending guard and the shared key are what actually protect you. crypto.randomUUID() needs a secure context (HTTPS).

A checklist

The client generates the key from the event and reuses it on every retry.
A unique constraint on (tenant, key); the key and the effect commit together.
Same key plus different body is a 422, not a replay.
Retry 429 and 5xx and timeouts, with backoff, jitter and Retry-After. Never retry other 4xx.
Queue consumers dedupe by message id in the same transaction as the effect.
State changes are compare-and-set; rowCount decides who won.
UI: disabled while pending, retry: false on mutations, one key per intent.

About the project

I work on Espresso Notify, a push notification service for iOS, Android and web with a dashboard and a REST API. Its send routes follow this contract, with the key as a field of the JSON body, idempotency_key (up to 128 bytes). Repeating a send with the same key and body answers 202 with duplicate_ignored and the id of the first send; the same key with another body answers 422 idempotency_key_reused; a refused call stores nothing, so the same key works once you fix the request. The docs include the retry table (429 with Retry-After, 5xx, timeouts with the same key) and the Node library adds a random key per call when you don't pass one. It is free up to 10,000 devices.

The contract and the retry table: https://docs.espressonotify.com/docs/api/reliable-sending
The Node library's retries and key: https://docs.espressonotify.com/docs/server-libraries/node

A question for the comments: where do you keep the line between "the same request" and "a different body" when you compare bodies for a key? Canonical JSON hash, a subset of fields, or something else? And how do you handle a key whose first request is still in flight when the retry arrives?

Push notifications for React Native and the web, priced per device instead of per message

Espresso Notify — Thu, 29 Oct 2026 20:19:31 +0000

Most push notification services charge by the message or by the monthly active user, and both grow faster than your app. We built Espresso Notify around a simpler unit: the active device. A device counts when it used your app in the last 30 days; send it one push or fifty, the price is the same. The first 10,000 devices are free.

What you get

One dashboard to write a campaign once and send it to iOS, Android and browsers together.
Audiences: segments by properties and behavior, plus test devices.
Delivery you can trust: every send shows delivered, opened and failed per device, with the failure reason (for example a token the device no longer uses).
A REST API for transactional pushes, with idempotency keys so a retry never sends twice.
Guardrails: quiet hours and frequency capping.
Journeys and A/B tests for the campaigns that need more than one message.

Setting up a React Native app

The React Native SDK ships on npm as @espresso-notify/react-native. One command sets it up in Expo apps and in React Native CLI apps:

npx @espresso-notify/react-native@latest setup

The wizard reads your package.json. In an Expo project (Expo SDK 53 or newer) it installs the packages that match your Expo SDK and adds the config plugin. In a React Native CLI project (React Native 0.79 or newer) it installs the Firebase and notification packages, adds the lines your Podfile, Gradle files and AppDelegate need, and lists what is left for you, such as your Firebase files.

From there the quickstarts walk through registering the device, identifying the user and sending a first push from the dashboard: https://docs.espressonotify.com/docs/react-native/expo for Expo and https://docs.espressonotify.com/docs/react-native/bare for React Native CLI. Web push has its own guide in the same docs.

Why per device

Per-message pricing punishes the apps that talk to their users the most, and MAU pricing counts people who never get a notification. Counting active devices matches what actually costs money to run, and it is easy to predict: you know how many devices installed your app last month.

Try it free at https://espressonotify.com. We would love to hear what is hard about push for your team today.