Errors & idempotency¶
Idempotency¶
Tax-Bridge derives a stable 32-hex request id from your external_ref (plus
shop and document type). Re-submitting the same logical invoice returns the
same fiscalization instead of signing it twice.
- Make
external_refunique per shop and per document. - Safe to retry a
5xxor a network timeout — you will not double-fiscalize. - A refund is a different document, so it gets its own id.
Transient vs permanent¶
The sandbox V-SDC fails transiently a large fraction of the time. Tax-Bridge classifies errors and retries the transient ones for you:
| Class | Examples | Behaviour |
|---|---|---|
| Transient | 500/502/503/504, 408, 429, timeouts |
Quick in-process retry, then durable backoff. |
| Permanent | 4xx validation, auth/cert failure |
Returned immediately; fix and resubmit. |
Error shape¶
{ "detail": "Tax label 'Z' is not valid for this shop" }
| HTTP | Meaning |
|---|---|
400 / 422 |
Validation error (bad schema, unknown tax label, non-2dp amount). |
401 |
Missing or invalid API key. |
403 |
The shop does not belong to your tenant. |
429 |
Rate limited. |
502 / 503 |
Upstream V-SDC transiently unavailable (will be retried). |