Error Codes Reference

This page is the centralized reference for error responses across all fiskaly APIs. Use the interactive explorer below to search and filter errors, or scroll down for the static reference tables.

36 errors found

Static Reference

Start with the troubleshooting decision tree if you have an error and need a quick answer, or browse the product-specific tables below for detailed error codes.

Error Response Format

All fiskaly APIs return errors in a consistent JSON format:

{
  "status_code": 400,
  "error": "Bad Request",
  "code": "E_SOME_ERROR",
  "message": "A human-readable description of what went wrong"
}

Field	Type	Description
`status_code`	integer	HTTP status code
`error`	string	HTTP status text
`code`	string	fiskaly-specific error code (prefixed with `E_`)
`message`	string	Human-readable error description

HTTP Status Codes

2xx — Success

Code	Meaning	When You See It
`200`	OK	Request succeeded, response body contains the result
`201`	Created	Resource created successfully
`204`	No Content	Request succeeded, no response body (e.g., DELETE operations)

4xx — Client Errors

These indicate a problem with your request. Do not retry with the same payload — fix the issue first.

Code	Meaning	Common Causes
`400`	Bad Request	Malformed JSON, missing required fields, invalid field values
`401`	Unauthorized	Expired or missing access token, invalid API credentials
`403`	Forbidden	Insufficient permissions for the requested resource
`404`	Not Found	Resource does not exist, or incorrect URL path
`409`	Conflict	Resource already exists (duplicate creation attempt)
`422`	Unprocessable Entity	Valid JSON but semantically incorrect (e.g., invalid state transition)
`423`	Locked	Resource is currently locked by another operation
`429`	Too Many Requests	Rate limit exceeded — back off and retry with exponential delay

5xx — Server Errors

These indicate a temporary problem on fiskaly’s side. Safe to retry with exponential backoff.

Code	Meaning	Action
`500`	Internal Server Error	Retry after a brief delay; if persistent, check status.fiskaly.com
`502`	Bad Gateway	Upstream service temporarily unavailable; retry
`503`	Service Unavailable	Service is temporarily down for maintenance; retry
`504`	Gateway Timeout	Request timed out upstream; retry with longer timeout

Authentication Errors

These are the most common errors developers encounter during integration.

Error Code	HTTP Status	Cause	Fix
`E_UNAUTHORIZED_ACCESS`	401	Access token expired or not provided	Re-authenticate using your API key and secret
`E_INVALID_CREDENTIALS`	401	API key or secret is incorrect	Verify credentials in the HUB
`E_TOKEN_EXPIRED`	401	JWT access token has expired	Use the refresh token, or re-authenticate
`E_ACCESS_FORBIDDEN`	403	Your API key does not have permission for this resource	Check API key scopes in the HUB

Token Lifecycle

API Key + Secret  →  POST /auth  →  access_token (24h) + refresh_token (48h)
                                         │
                                         ├── Use for all API calls
                                         │
                                         └── On 401 → re-authenticate (not on every request)

💡Don't re-authenticate on every request

The access token is valid for 24 hours and the refresh token for 48 hours. Re-authenticating on every request adds unnecessary latency to your checkout process. Cache the token and only refresh when you receive a 401 response.

SIGN DE — TSS Errors

Error Code	HTTP Status	Cause	Fix
`E_TSS_NOT_FOUND`	404	TSS ID does not exist	Verify the TSS ID; list all TSS via `GET /tss`
`E_TSS_NOT_INITIALIZED`	400	TSS has not been initialized yet	Follow all necessary steps: create TSS, update it to `UNINITIALIZED`, set Admin PIN, login as Admin and set TSS to `INITIALIZED`
`E_TSS_DISABLED`	400	TSS has been disabled	TSS can no longer sign transactions, create a new TSS
`E_TSS_IN_USE`	409	TSS is being modified by another request	Wait and retry
`E_CLIENT_NOT_FOUND`	404	Client ID does not exist for this TSS	Create a client via `PUT /tss/{tss_id}/client/{client_id}`
`E_CLIENT_NOT_REGISTERED`	400	Client exists but is not registered	Register the client before creating transactions
`E_TX_NOT_FOUND`	404	Transaction ID does not exist	Verify the transaction ID and TSS context
`E_TX_INVALID_STATE`	422	Transaction is in a state that does not allow this operation	Check the current transaction state; follow the state machine
`E_EXPORT_NOT_FOUND`	404	Export ID does not exist	Verify export ID; exports may take time to process
`E_EXPORT_IN_PROGRESS`	409	Export is still being generated	Poll the export status until `state: COMPLETED`

SUBMIT DE Errors

Error Code	HTTP Status	Cause	Fix
`E_ESTABLISHMENT_NOT_FOUND`	404	Establishment ID not found	Verify the establishment exists for your organization
`E_TAXPAYER_NOT_FOUND`	404	Taxpayer record not found	Create the taxpayer resource first
`E_TAXPAYER_ADDRESS_NOT_FOUND`	404	Taxpayer address not configured	Add address data to the taxpayer resource
`E_TAXPAYER_PERSON_NOT_FOUND`	404	Taxpayer person record missing	Add person data to the taxpayer resource
`E_SUBMISSION_NOT_FOUND`	404	Submission ID not found	Verify submission ID; check that the submission was created
`E_CLIENT_ADDITIONAL_DATA_NOT_FOUND`	404	Client additional data missing	Provide the required additional data for the client
`E_LOCKED_RESOURCE`	423	Resource is locked by an ongoing operation	Wait for the current operation to complete, then retry

DSFINVK DE Errors

Error Code	HTTP Status	Cause	Fix
`E_CASH_REGISTER_NOT_FOUND`	404	Cash register not found	Create the cash register first via the DSFinV-K API
`E_CASH_POINT_CLOSING_NOT_FOUND`	404	Cash point closing not found	Verify the closing ID
`E_VAT_DEFINITION_NOT_FOUND`	404	VAT definition not configured	Create VAT definitions before inserting closings
`E_INVALID_CLOSING_DATA`	400	Closing payload does not match expected schema	Validate your payload against the DSFinV-K specification

Unified API — Common Errors

These errors are shared across all Unified API products (SIGN FR, SIGN IT, SIGN ES). All three APIs use the same authentication, organization, and resource-management layer.

Error Code	HTTP Status	Cause	Fix
`E_ORGANIZATION_NOT_FOUND`	404	Organization ID does not exist	Verify org ID; ensure it was created under the correct GROUP
`E_TAXPAYER_NOT_COMMISSIONED`	400	Taxpayer exists but state is not `COMMISSIONED`	Update taxpayer state to `COMMISSIONED` before operations
`E_IDEMPOTENCY_KEY_REUSED`	409	Idempotency key was already used for a different request	Generate a fresh UUID for each new request
`E_API_VERSION_NOT_SUPPORTED`	400	`X-Api-Version` header contains unsupported date	Use the latest supported version (e.g. `2026-02-03`)
`E_SCOPE_IDENTIFIER_MISSING`	400	`X-Scope-Identifier` header not provided	Include the organization ID in `X-Scope-Identifier`
`E_SUBJECT_NOT_FOUND`	404	Subject (API key) not found	Verify subject was created under the correct organization
`E_TOKEN_INVALID`	401	Token is malformed or expired	Re-authenticate via `POST /api/v1/auth/token`
`E_LOCATION_NOT_COMMISSIONED`	400	Location exists but not commissioned	Update location state to `COMMISSIONED`
`E_SYSTEM_NOT_COMMISSIONED`	400	System exists but not commissioned	Update system state to `COMMISSIONED`

💡Idempotency keys across all Unified APIs

All Unified API products support the X-Idempotency-Key header on mutating requests. The key-value pairs expire after 24 hours. If you reuse a key with a different payload, you will receive a 422 Unprocessable Entity. If the original request is still being processed, you will receive a 409 Conflict.

SIGN FR — Specific Errors

Error Code	HTTP Status	Cause	Fix
`E_RECORD_INVALID_OPERATION`	422	Record operation type not valid for current state	Check the Intention → Transaction flow; ensure correct sequence
`E_RECORD_INTENTION_REQUIRED`	400	Transaction record created without prior Intention	Create an Intention record first, then reference its ID
`E_TAXPAYER_CREDENTIALS_INVALID`	400	French fiscalization credentials (NF 525) are invalid	Verify `tax_id_number` (SIREN) and credentials
`E_CLOSURE_IN_PROGRESS`	409	A fiscal closure is already running	Wait for current closure to complete

SIGN IT — Specific Errors

Error Code	HTTP Status	Cause	Fix
`E_RT_DEVICE_NOT_FOUND`	404	Registratore Telematico device not found	Verify the RT device was created and commissioned
`E_RT_SUBMISSION_FAILED`	502	Submission to Agenzia delle Entrate failed	Retry; check AdE service status if persistent
`E_LOTTERY_CODE_INVALID`	400	Receipt lottery code format is invalid	Ensure lottery code is 8 alphanumeric characters
`E_FISCAL_CODE_INVALID`	400	Italian codice fiscale format is incorrect	Verify the 16-character fiscal code format

SIGN ES — Validation Errors

SIGN ES returns validation errors in a validations array on the response, each with a code and description. These are specific to TicketBAI / Verifactu / SII transmissions.

Validation Code	Cause
`V_TICKETBAI`	Unknown or unhandled error from TicketBAI
`V_XSD_SCHEMA_NOT_COMPLY`	XML file does not comply with the XML schema
`V_INVOICE_WITHOUT_LINES`	XML file does not include detail lines
`V_REQUIRED_FIELD_MISSING_OR_INCORRECT`	Compulsory data is missing or incorrect
`V_INVOICE_ALREADY_REGISTERED`	Invoice with the same number/series/year was already registered
`V_SERVICE_NOT_AVAILABLE`	The reception service is not available
`V_INCORRECT_SENDER_CERTIFICATE`	The sender certificate is unknown
`V_INVALID_SENDER_CERTIFICATE`	The sender certificate is not valid
`V_WRONG_SIGNATURE`	Signature validation failed
`V_INCORRECT_INVOICE_CHAINING`	Invoice chaining was incorrect
`V_INVALID_TBAI_LICENSE`	TicketBAI licence not registered or not valid
`V_DEVICE_NOT_REGISTERED`	Device certificate used for sending is pending registration
`V_EXPIRED_SIGNATURE_CERTIFICATE`	Certificate used to sign the TicketBAI file has expired
`V_EXPIRED_SENDER_CERTIFICATE`	Sender certificate is not valid or has expired
`V_EXPIRED_SIGNER_CERTIFICATE`	Certificate used for signing is not valid or has expired
`V_FULL_AMOUNT_MISMATCH`	Sum of line `full_amount` entries does not equal invoice `full_amount`
`V_ISSUE_DATE_OUT_OF_RANGE`	Issue date is older than 20 years or in the future
`V_INVALID_VAT_RATE`	VAT rate is not a valid value for the taxpayer’s region
`V_INVOICE_ALREADY_CANCELLED`	Invoice was already cancelled
`V_INVOICE_ALREADY_CORRECTED`	Invoice was already corrected
`V_INCOMPATIBLE_VAT_SYSTEMS`	Provided invoice systems are not compatible with each other
`V_INCORRECT_ITEM_VAT_CALCULATION`	An invoice item has an incorrectly applied VAT calculation

📘SIGN ES validation errors are non-blocking

Validation errors appear in the validations array of the response but do not necessarily prevent the record from being created. Check the record state field (REJECTED or FAILED) to determine if the error was fatal.

Timeout Recommendations

Different operations have different expected durations. Configure your timeouts accordingly:

Operation	Recommended Timeout	Notes
Authentication (`POST /auth`)	3-4 seconds	Fast operation; do not block checkout
Transaction signing (`PUT /tx`)	3-5 seconds	Should never block the POS
TSS creation / initialization	30 seconds	One-time setup; heavier processing
DSFinV-K cash point closings	Up to 10 minutes	Heavy processing with large datasets
Export generation	Poll-based	Use async polling, not synchronous wait

⚠️Never block the checkout

Set transaction signing timeouts between 3-5 seconds. A missing signature does not make a receipt non-compliant (see AEAO to 146a, Point 7). Add a note like “TSS not available” to unsigned receipts and include them in the DSFinV-K export.

💡Make timeouts configurable

Allow administrators to adjust timeout values (e.g., 1.5-5 seconds for transactions) without code changes. This saves development cycles and adapts to varying network conditions.

Retry Strategy

For transient errors (5xx, timeouts, rate limits), use exponential backoff:

async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;

      const isRetryable =
        error.status >= 500 ||
        error.status === 429 ||
        error.code === "ETIMEDOUT";

      if (!isRetryable) throw error;

      const delay = Math.min(1000 * 2 ** attempt, 30000);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Troubleshooting Decision Tree

Got an error?
  │
  ├── 401 Unauthorized
  │     └── Is your token expired?
  │           ├── Yes → Re-authenticate with API key + secret
  │           └── No  → Check credentials in the HUB
  │
  ├── 400 Bad Request
  │     └── Check the `message` field for which field is invalid
  │           └── Validate your JSON payload against the API schema
  │
  ├── 404 Not Found
  │     └── Does the resource exist?
  │           ├── Check the ID is correct (UUIDv4 format)
  │           └── Ensure the resource was created in the correct environment (TEST vs LIVE)
  │
  ├── 409 Conflict
  │     └── Resource already exists or is being modified
  │           └── Use GET to check current state before retrying
  │
  ├── 429 Rate Limited
  │     └── Back off with exponential delay
  │           └── Check if you are re-authenticating on every request (don't)
  │
  └── 5xx Server Error
        └── Check status.fiskaly.com
              ├── Known incident → Wait for resolution
              └── No incident → Retry with exponential backoff; contact support if persistent

Service Status

Monitor fiskaly service health at status.fiskaly.com.

Common integration mistakes

These are the errors fiskaly support sees most often from teams during their first integration. Avoiding them saves significant debugging time.

Mistake	What happens	How to avoid it
Re-authenticating on every request	`429` rate limit errors; unnecessary latency on every checkout	Cache the access token (24h TTL). Only re-authenticate on `401`.
Not saving the `admin_puk`	Cannot set the Admin PIN on the TSS; stuck in `UNINITIALIZED` state	Store the `admin_puk` from the TSS creation response immediately.
Reusing UUIDs	`409 Conflict` errors when creating TSS, clients, or transactions	Generate a fresh UUIDv4 for every resource creation call.
Blocking checkout on signing failure	Customers wait indefinitely if the TSS is slow or unavailable	Set a 3-5 second timeout on signing. Issue the receipt with “TSS not available” and retry later.
Using TEST credentials in LIVE (or vice versa)	`401 Unauthorized` — credentials are environment-scoped	Verify the base URL matches the API key’s environment. TEST and LIVE are completely separate.
Skipping TSS initialization	`400 E_TSS_NOT_INITIALIZED` when creating clients or transactions	Follow all necessary steps: create TSS, update it to `UNINITIALIZED`, set Admin PIN, login as Admin and set TSS to `INITIALIZED`.
Not handling `tx_revision` correctly	`422 E_TX_INVALID_STATE` or duplicate transaction errors	Start with `tx_revision=1` (ACTIVE), finish with `tx_revision=2` (FINISHED). Always increment.
Synchronous export polling	Timeouts on DSFinV-K export generation (can take up to 10 minutes)	Use async polling: trigger export, then poll status endpoint until `state: COMPLETED`.
Hardcoding timeouts	Development team cannot adjust without a code release	Make timeouts configurable (e.g., 1.5-5 seconds for transactions). Admin-adjustable is ideal.

Error Handling Guide

Best practices for SIGN DE timeout and error recovery

Submission Errors

SUBMIT DE specific error codes and status codes

API Reference

Full endpoint documentation for all fiskaly APIs

Was this page helpful?