Retry Queue

Monitor the fiscalization retry queue. Transactions that fail inline fiscalization are automatically retried with exponential backoff. All endpoints require authentication.

List retry queue entries

GET /v1/retry-queue

Returns a paginated list of retry queue entries for the authenticated account.

Query parameters

Parameter	Type	Default	Description
limit	integer	20	Items per page (max 100)
offset	integer	0	Pagination offset (max 10000)
status	string	--	Filter by status: pending, processing, completed, failed, dead

Example

# List all entries
curl https://api.zyntem.dev/v1/retry-queue \
  -H "Authorization: Bearer zyn_test_abc123def456..."

# Filter by status
curl "https://api.zyntem.dev/v1/retry-queue?status=pending&limit=10" \
  -H "Authorization: Bearer zyn_test_abc123def456..."

Response 200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "account_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "pending",
      "attempt": 3,
      "max_attempts": 50,
      "next_retry_at": "2026-03-09T15:00:00Z",
      "last_error": "connection timeout to tax authority",
      "created_at": "2026-03-09T14:30:01Z",
      "updated_at": "2026-03-09T14:45:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

---

Get retry queue stats

GET /v1/retry-queue/stats

Returns aggregate statistics for the retry queue (last 24 hours).

Example

curl https://api.zyntem.dev/v1/retry-queue/stats \
  -H "Authorization: Bearer zyn_test_abc123def456..."

Response 200 OK

{
  "pending": 5,
  "processing": 1,
  "completed": 142,
  "failed": 3,
  "dead": 0,
  "total": 151
}

---

Entry object

Field	Type	Description
id	uuid	Entry identifier
transaction_id	uuid	Associated transaction
account_id	uuid	Owning account
status	string	Entry status (see below)
attempt	integer	Current attempt number
max_attempts	integer	Maximum retry attempts (default: 50)
next_retry_at	datetime	When the next retry is scheduled
last_error	string	Error from the most recent attempt
webhook_url	string	Webhook URL for notifications (if configured)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Entry statuses

Status	Description
pending	Queued for retry
processing	Currently being retried
completed	Fiscalization succeeded
failed	Attempt failed, will retry
dead	Max attempts exceeded, moved to dead letter

Retry behavior

When a transaction fails inline fiscalization, it is automatically added to the retry queue:

1. Exponential backoff -- retry intervals increase with each attempt
2. Max 50 attempts -- after exhausting all attempts, the entry moves to dead status
3. Webhook notification -- if a webhook is configured, events are sent on completion (fiscalization.completed) or dead letter (fiscalization.dead_letter)

Transaction status flow

pending → processing → success
                     → failed → (retry) → processing → ...
                     → failed_permanent (dead letter)