Notifications: Understanding "Unknown Error"

When using Tatum Notifications, you may occasionally see the status "Unknown Error" in the dashboard. This article explains what this means, why it happens, and how to troubleshoot it.

What does "Unknown Error" mean?

Tatum sends webhooks to the callback URL you provided when creating a subscription.
If, at the moment of delivery, your server does not accept or process the webhook, we flag that attempt as failed.

In such cases, the notification is displayed in the dashboard with the status "Unknown Error".

Example:

Common reasons for webhook delivery failures

• Server unavailability: Your server or endpoint may have been down or unreachable when the webhook was sent.
• High traffic volume: Subscribing to addresses with many transactions (e.g., hot wallets) can generate a very high webhook volume, potentially overloading your server.
• Firewall or network rules: Restrictions blocking Tatum’s requests.
• Timeouts: Your server took too long to respond to our webhook delivery.

What happens after an ingestion failure?

When a webhook fails, Tatum does not discard it. We use a retry mechanism to attempt delivery again.
Learn more: Webhook Retry Service

How does this affect my credits?

Every webhook attempt, including retries, consumes credits.
See details: Notifications Pricing

If your server is unable to ingest notifications for an extended period, retries can result in higher-than-expected credit usage.

How to prevent this?

• Ensure your server is highly available: Use a robust hosting setup to minimize downtime.
• Scale for high-traffic subscriptions: If subscribing to addresses with high activity, prepare for large webhook volumes.
• Log incoming requests: Ensure you log all requests from Tatum for troubleshooting.
• Whitelist Tatum IPs (if using firewalls): Ensure Tatum can reach your endpoint.

Next steps if you see "Unknown Error"

• Check your server logs during the reported time to verify if requests reached your endpoint.
• Validate endpoint performance: Ensure your server can handle high request loads.
• Update the callback URL: If the URL stored in the subscription is no longer valid, you can update it. This will only apply to new notifications. Those in "retry mode" will not be retroactively updated.