The problem
Every channel fails differently — APNs returns reasons like InvalidProviderToken, FCM returns messaging/registration-token-not-registered, SMTP and SMS gateways return their own codes. Raw, those are noise. Payghaam normalizes them so you see problems with fixes, not a log of opaque strings.
Normalized categories
Every failure is classified into one category and a scope:
| Category | Means | Retried? |
|---|---|---|
| CONFIG | Credentials/setup wrong — the whole channel is down (e.g. bad APNs key). | No |
| TOKEN | One device's token or address is invalid/expired. | No |
| RATE | The provider throttled us. | Yes |
| PROVIDER_DOWN | 5xx / timeout / connection — transient, provider-side. | Yes |
| PAYLOAD | Message too large or malformed. | No |
| CONSENT | Opted out / capped — a skip, not an error. | No |
Terminal failures (bad token, bad config, bad payload) are not retried — there's no point burning attempts on a dead end. The category and machine code are stored on each MessageDelivery alongside the raw provider reason.
Issues, not a firehose
Identical failures roll up into a single issue, deduplicated on (project, channel, code), with an occurrence count. Five thousand InvalidProviderToken failures become one critical issue showing ×5000 — not five thousand notifications.
- Critical — a channel-wide config error; the channel is effectively down.
- Warning — provider outages, throttling, or a spike in dead device tokens.
- Info — a few dead tokens or consent skips (normal background noise).
Auto-resolution
Issues clean themselves up. A circuit breaker tripping opens a provider-down issue; its recovery resolves it. A successful send clears channel-wide config issues (you fixed the key). Device-level issues clear as tokens refresh. You can also snooze or resolve any issue manually.
Not just push
The same pipeline covers event ingestion (a backed-up buffer) and journeys (a step erroring), so one surface shows every operational problem across push, email, SMS, events, and automations.
The notification manager
Open issues appear in the top-bar bell (with a live count), a persistent banner for critical problems, and the full Notifications page — each with a plain-language hint and a deep link to the fix (e.g. straight to channel settings).
Note