Queues & Retries

URA API downtime is inevitable. TaxBridge uses intelligent queuing and exponential backoff to ensure your invoices get fiscalized even when the government systems are struggling.

The Problem: Unpredictable URA

EFRIS is a critical government system, but it's not always available. Network issues, maintenance windows, and peak loads can cause failures that would otherwise lose your fiscal data.

Common Failure Scenarios

• Network timeout during T109 submission
• URA server maintenance windows
• Temporary cryptographic key issues
• High load during tax season peaks
• Transient database connectivity problems

The Solution: Resilient Processing

TaxBridge treats fiscalization as an asynchronous, retryable operation. When you confirm a TaxIntent, it enters a queue for processing with intelligent retry logic.

Queue Immediately

Your request returns instantly. Processing happens in the background.

Retry Automatically

Failed submissions retry with exponential backoff up to 24 hours.

Webhook Notification

Get notified when fiscalization succeeds or permanently fails.

Queue Processing Flow

When you confirm a TaxIntent, it goes through this resilient processing pipeline.

1

Queue Entry

TaxIntent status changes to "processing". Job enters Redis queue with priority.

2

Handshake Check

Verify cryptographic keys and session validity. Refresh if needed.

3

EFRIS Submission

Encrypt and submit T109 payload. Handle immediate success/failure.

4

Polling & Confirmation

For async responses, poll T111 until final status is determined.

5

Webhook Delivery

Notify your application of success or final failure.

Retry Strategy

TaxBridge uses exponential backoff with jitter to handle transient failures without overwhelming URA systems or creating thundering herd problems.

// Retry Configuration

const RETRY_CONFIG = {
  maxAttempts: 10,
  initialDelay: 1000,  // 1 second
  maxDelay: 3600000,  // 1 hour
  backoffMultiplier: 2,
  jitter: true
};

Attempt	Delay	Cumulative Time	Success Rate
1	1s	1s	~50%
2	2s	3s	~75%
3	4s	7s	~87%
5	16s	31s	~97%
10	17m	~34m	~99.9%

Failure Classification

Not all failures should be retried. TaxBridge intelligently classifies errors to determine the appropriate response.

Retryable Errors

Network timeouts, temporary server errors, rate limits. These get exponential backoff retry.

500 Internal Server Error, 502 Bad Gateway, ECONNRESET

Correctable Errors

Business logic errors that can be fixed. Status becomes "requires_correction" for manual intervention.

Unit mismatch, Invalid goods code, Price deviation

Permanent Failures

Configuration errors or invalid requests. No retry attempted.

Invalid device, Bad signature, Malformed payload

Webhook Notifications

Get notified asynchronously when your TaxIntents complete processing. Configure webhook URLs in your dashboard.

# Success Webhook

POST https://your-app.com/webhooks/taxbridge
Content-Type: application/json

{
  "event": "tax_intent.succeeded",
  "data": {
    "id": "ti_xyz789",
    "status": "succeeded",
    "fdn": "1234567890",
    "verification_code": "ABC123XYZ",
    "qrcode": "base64_encoded_qr"
  }
}

# Failure Webhook

POST https://your-app.com/webhooks/taxbridge
Content-Type: application/json

{
  "event": "tax_intent.failed",
  "data": {
    "id": "ti_xyz789",
    "status": "failed",
    "last_error": "Network timeout after 10 retries"
  }
}

Monitoring & Observability

Track queue health and retry patterns through comprehensive logging and metrics in your dashboard.

Queue Metrics

Active Jobs 23

Waiting 156

Completed (24h) 2,847

Failed (24h) 12

Success Rates

First Attempt 94.2%

After Retry 99.7%

Final Success 99.95%

Best Practices

1

Design for Async

Build your application to handle webhooks and status polling, not synchronous responses.

2

Monitor Queue Health

Set up alerts for queue depth and failure rates to catch issues before they impact users.

3

Handle Webhook Failures

Implement webhook retry logic in your application since TaxBridge expects 2xx responses.