Referencia de códigos de error

Esta página es la referencia centralizada para las respuestas de error de todas las API de fiskaly. Usa el explorador interactivo de abajo para buscar y filtrar errores, o desplázate hacia abajo para consultar las tablas de referencia estáticas.

36 errors found

Referencia estática

Comienza por el árbol de decisión para la resolución de problemas si tienes un error y necesitas una respuesta rápida, o consulta las tablas específicas de cada producto para obtener códigos de error detallados.

Formato de respuesta de error

Todas las API de fiskaly devuelven los errores en un formato JSON consistente:

{
  "status_code": 400,
  "error": "Bad Request",
  "code": "E_SOME_ERROR",
  "message": "Una descripción legible por humanos de lo que salió mal"
}

Campo	Tipo	Descripción
`status_code`	entero	Código de estado HTTP
`error`	cadena	Texto de estado HTTP
`code`	cadena	Código de error específico de fiskaly (prefijado con `E_`)
`message`	cadena	Descripción del error legible por humanos

Códigos de estado HTTP

2xx — Éxito

Código	Significado	Cuándo aparece
`200`	OK	La solicitud se realizó correctamente; el cuerpo de la respuesta contiene el resultado
`201`	Creado	Recurso creado correctamente
`204`	Sin contenido	La solicitud se realizó correctamente, sin cuerpo de respuesta (p. ej., operaciones DELETE)

4xx — Errores del cliente

Estos indican un problema con tu solicitud. No reintentar con el mismo payload — primero corrige el problema.

Código	Significado	Causas comunes
`400`	Solicitud incorrecta	JSON mal formado, campos obligatorios faltantes, valores de campo inválidos
`401`	No autorizado	Token de acceso caducado o faltante, credenciales de API inválidas
`403`	Prohibido	Permisos insuficientes para el recurso solicitado
`404`	No encontrado	El recurso no existe, o ruta URL incorrecta
`409`	Conflicto	El recurso ya existe (intento de creación duplicada)
`422`	Entidad no procesable	JSON válido pero semánticamente incorrecto (p. ej., transición de estado inválida)
`423`	Bloqueado	El recurso está bloqueado actualmente por otra operación
`429`	Demasiadas solicitudes	Límite de frecuencia superado — espera y reintenta con retraso exponencial

5xx — Errores del servidor

Estos indican un problema temporal en el lado de fiskaly. Se puede reintentar con backoff exponencial.

Código	Significado	Acción
`500`	Error interno del servidor	Reintentar tras un breve retraso; si persiste, consulta status.fiskaly.com
`502`	Gateway incorrecto	Servicio upstream temporalmente no disponible; reintentar
`503`	Servicio no disponible	El servicio está temporalmente caído por mantenimiento; reintentar
`504`	Timeout del gateway	La solicitud agotó el tiempo de espera en upstream; reintentar con mayor timeout

Errores de autenticación

Estos son los errores más comunes que los desarrolladores encuentran durante la integración.

Código de error	Estado HTTP	Causa	Solución
`E_UNAUTHORIZED_ACCESS`	401	Token de acceso caducado o no proporcionado	Vuelve a autenticarte usando tu clave y secreto de API
`E_INVALID_CREDENTIALS`	401	La clave o el secreto de API son incorrectos	Verifica las credenciales en el HUB
`E_TOKEN_EXPIRED`	401	El token de acceso JWT ha caducado	Usa el token de actualización o vuelve a autenticarte
`E_ACCESS_FORBIDDEN`	403	Tu clave de API no tiene permiso para este recurso	Comprueba los ámbitos de la clave de API en el HUB

Ciclo de vida del token

Clave API + Secreto  →  POST /auth  →  access_token (24h) + refresh_token (48h)
                                            │
                                            ├── Usar en todas las llamadas a la API
                                            │
                                            └── Con 401 → volver a autenticarse (no en cada solicitud)

💡No te autentiques de nuevo en cada solicitud

El token de acceso es válido durante 24 horas y el token de actualización durante 48 horas. Volver a autenticarse en cada solicitud añade latencia innecesaria al proceso de pago. Almacena en caché el token y actualízalo solo cuando recibas una respuesta 401.

SIGN DE — Errores de TSS

Código de error	Estado HTTP	Causa	Solución
`E_TSS_NOT_FOUND`	404	El ID del TSS no existe	Verifica el ID del TSS; lista todos los TSS mediante `GET /tss`
`E_TSS_NOT_INITIALIZED`	400	El TSS aún no ha sido inicializado	Sigue todos los pasos necesarios: crea el TSS, actualízalo a `UNINITIALIZED`, establece el PIN Admin, inicia sesión como Admin y cambia el TSS a `INITIALIZED`
`E_TSS_DISABLED`	400	El TSS ha sido desactivado	El TSS ya no puede firmar transacciones; crea un TSS nuevo
`E_TSS_IN_USE`	409	El TSS está siendo modificado por otra solicitud	Espera y reintenta
`E_CLIENT_NOT_FOUND`	404	El ID del cliente no existe para este TSS	Crea un cliente mediante `PUT /tss/{tss_id}/client/{client_id}`
`E_CLIENT_NOT_REGISTERED`	400	El cliente existe pero no está registrado	Registra el cliente antes de crear transacciones
`E_TX_NOT_FOUND`	404	El ID de la transacción no existe	Verifica el ID de la transacción y el contexto del TSS
`E_TX_INVALID_STATE`	422	La transacción está en un estado que no permite esta operación	Comprueba el estado actual de la transacción; sigue la máquina de estados
`E_EXPORT_NOT_FOUND`	404	El ID de exportación no existe	Verifica el ID de exportación; las exportaciones pueden tardar en procesarse
`E_EXPORT_IN_PROGRESS`	409	La exportación aún se está generando	Sondea el estado de la exportación hasta que `state: COMPLETED`

Errores de SUBMIT DE

Código de error	Estado HTTP	Causa	Solución
`E_ESTABLISHMENT_NOT_FOUND`	404	ID de establecimiento no encontrado	Verifica que el establecimiento existe para tu organización
`E_TAXPAYER_NOT_FOUND`	404	Registro de contribuyente no encontrado	Crea primero el recurso de contribuyente
`E_TAXPAYER_ADDRESS_NOT_FOUND`	404	Dirección del contribuyente no configurada	Añade datos de dirección al recurso de contribuyente
`E_TAXPAYER_PERSON_NOT_FOUND`	404	Registro de persona del contribuyente faltante	Añade datos de persona al recurso de contribuyente
`E_SUBMISSION_NOT_FOUND`	404	ID de declaración no encontrado	Verifica el ID de declaración; comprueba que la declaración fue creada
`E_CLIENT_ADDITIONAL_DATA_NOT_FOUND`	404	Datos adicionales del cliente faltantes	Proporciona los datos adicionales requeridos para el cliente
`E_LOCKED_RESOURCE`	423	El recurso está bloqueado por una operación en curso	Espera a que se completa la operación actual y vuelve a intentarlo

Errores de DSFINVK DE

Código de error	Estado HTTP	Causa	Solución
`E_CASH_REGISTER_NOT_FOUND`	404	Caja registradora no encontrada	Crea primero la caja registradora mediante la API DSFinV-K
`E_CASH_POINT_CLOSING_NOT_FOUND`	404	Cierre de punto de venta no encontrado	Verifica el ID de cierre
`E_VAT_DEFINITION_NOT_FOUND`	404	Definición de IVA no configurada	Crea las definiciones de IVA antes de insertar cierres
`E_INVALID_CLOSING_DATA`	400	El payload de cierre no coincide con el esquema esperado	Valida tu payload frente a la especificación DSFinV-K

API Unificada — Errores comunes

Estos errores son compartidos por todos los productos de la API Unificada (SIGN FR, SIGN IT, SIGN ES). Las tres APIs usan la misma capa de autenticación, organización y gestión de recursos.

Código de error	Estado HTTP	Causa	Solución
`E_ORGANIZATION_NOT_FOUND`	404	El ID de organización no existe	Verifica el ID de la org; asegúrate de que fue creada bajo el GROUP correcto
`E_TAXPAYER_NOT_COMMISSIONED`	400	El contribuyente existe pero su estado no es `COMMISSIONED`	Actualiza el estado del contribuyente a `COMMISSIONED` antes de operar
`E_IDEMPOTENCY_KEY_REUSED`	409	La clave de idempotencia ya fue usada para otra solicitud	Genera un nuevo UUID para cada nueva solicitud
`E_API_VERSION_NOT_SUPPORTED`	400	El header `X-Api-Version` contiene una fecha no compatible	Usa la versión más reciente compatible (p. ej., `2026-02-03`)
`E_SCOPE_IDENTIFIER_MISSING`	400	Header `X-Scope-Identifier` no proporcionado	Incluye el ID de organización en `X-Scope-Identifier`
`E_SUBJECT_NOT_FOUND`	404	Subject (clave API) no encontrado	Verifica que el subject fue creado bajo la organización correcta
`E_TOKEN_INVALID`	401	El token está malformado o ha caducado	Vuelve a autenticarte mediante `POST /api/v1/auth/token`
`E_LOCATION_NOT_COMMISSIONED`	400	La ubicación existe pero no está comisionada	Actualiza el estado de la ubicación a `COMMISSIONED`
`E_SYSTEM_NOT_COMMISSIONED`	400	El sistema existe pero no está comisionado	Actualiza el estado del sistema a `COMMISSIONED`

💡Claves de idempotencia en todas las API Unificadas

Todos los productos de la API Unificada soportan el header X-Idempotency-Key en solicitudes mutantes. Los pares clave-valor caducan tras 24 horas. Si reutilizas una clave con un payload diferente, recibirás un 422 Unprocessable Entity. Si la solicitud original aún se está procesando, recibirás un 409 Conflict.

SIGN FR — Errores específicos

Código de error	Estado HTTP	Causa	Solución
`E_RECORD_INVALID_OPERATION`	422	El tipo de operación del registro no es válido para el estado actual	Comprueba el flujo Intention → Transaction; asegura la secuencia correcta
`E_RECORD_INTENTION_REQUIRED`	400	Registro de transacción creado sin Intention previa	Crea primero un registro Intention y luego referencia su ID
`E_TAXPAYER_CREDENTIALS_INVALID`	400	Las credenciales de fiscalización francesa (NF 525) son inválidas	Verifica `tax_id_number` (SIREN) y las credenciales
`E_CLOSURE_IN_PROGRESS`	409	Ya hay un cierre fiscal en curso	Espera a que se completa el cierre actual

SIGN IT — Errores específicos

Código de error	Estado HTTP	Causa	Solución
`E_RT_DEVICE_NOT_FOUND`	404	Dispositivo Registratore Telematico no encontrado	Verifica que el dispositivo RT fue creado y comisionado
`E_RT_SUBMISSION_FAILED`	502	Envío a Agenzia delle Entrate fallido	Reintenta; comprueba el estado del servicio AdE si persiste
`E_LOTTERY_CODE_INVALID`	400	El formato del código de la lotería de recibos es inválido	Asegúrate de que el código de la lotería tiene 8 caracteres alfanuméricos
`E_FISCAL_CODE_INVALID`	400	El formato del codice fiscale italiano es incorrecto	Verifica el formato del código fiscal de 16 caracteres

SIGN ES — Errores de validación

SIGN ES devuelve los errores de validación en un array validations en la respuesta, cada uno con un code y una description. Estos son específicos de las transmisiones TicketBAI / Verifactu / SII.

Código de validación	Causa
`V_TICKETBAI`	Error desconocido o no gestionado de TicketBAI
`V_XSD_SCHEMA_NOT_COMPLY`	El archivo XML no cumple con el esquema XML
`V_INVOICE_WITHOUT_LINES`	El archivo XML no incluye líneas de detalle
`V_REQUIRED_FIELD_MISSING_OR_INCORRECT`	Faltan datos obligatorios o son incorrectos
`V_INVOICE_ALREADY_REGISTERED`	Ya se registró una factura con el mismo número/serie/año
`V_SERVICE_NOT_AVAILABLE`	El servicio de recepción no está disponible
`V_INCORRECT_SENDER_CERTIFICATE`	El certificado del remitente es desconocido
`V_INVALID_SENDER_CERTIFICATE`	El certificado del remitente no es válido
`V_WRONG_SIGNATURE`	La validación de la firma ha fallado
`V_INCORRECT_INVOICE_CHAINING`	El encadenamiento de facturas es incorrecto
`V_INVALID_TBAI_LICENSE`	Licencia TicketBAI no registrada o no válida
`V_DEVICE_NOT_REGISTERED`	El certificado de dispositivo usado para el envío está pendiente de registro
`V_EXPIRED_SIGNATURE_CERTIFICATE`	El certificado usado para firmar el archivo TicketBAI ha caducado
`V_EXPIRED_SENDER_CERTIFICATE`	El certificado del remitente no es válido o ha caducado
`V_EXPIRED_SIGNER_CERTIFICATE`	El certificado usado para firmar no es válido o ha caducado
`V_FULL_AMOUNT_MISMATCH`	La suma de los `full_amount` de las líneas no es igual al `full_amount` de la factura
`V_ISSUE_DATE_OUT_OF_RANGE`	La fecha de emisión tiene más de 20 años o es futura
`V_INVALID_VAT_RATE`	La tasa de IVA no es un valor válido para la región del contribuyente
`V_INVOICE_ALREADY_CANCELLED`	La factura ya fue cancelada
`V_INVOICE_ALREADY_CORRECTED`	La factura ya fue corregida
`V_INCOMPATIBLE_VAT_SYSTEMS`	Los sistemas de IVA proporcionados no son compatibles entre sí
`V_INCORRECT_ITEM_VAT_CALCULATION`	Un artículo de la factura tiene un cálculo de IVA aplicado incorrectamente

📘Los errores de validación de SIGN ES no son bloqueantes

Los errores de validación aparecen en el array validations de la respuesta pero no impiden necesariamente que se crea el registro. Comprueba el campo state del registro (REJECTED o FAILED) para determinar si el error fue fatal.

Recomendaciones de timeout

Las diferentes operaciones tienen distintas duraciones esperadas. Configura tus timeouts en consecuencia:

Operación	Timeout recomendado	Notas
Autenticación (`POST /auth`)	3-4 segundos	Operación rápida; no bloquear el pago
Firma de transacción (`PUT /tx`)	3-5 segundos	Nunca debe bloquear el TPV
Creación / inicialización del TSS	30 segundos	Configuración única; procesamiento más pesado
Cierres de punto de venta DSFinV-K	Hasta 10 minutos	Procesamiento pesado con grandes conjuntos de datos
Generación de exportación	Basado en sondeo	Usa sondeo asíncrono, no espera síncrona

⚠️Nunca bloquees el pago

Configura los timeouts de firma de transacciones entre 3 y 5 segundos. La falta de una firma no hace que un recibo sea no conforme (ver AEAO al 146a, Punto 7). Añade una nota como “TSS no disponible” a los recibos sin firma e inclúyelos en la exportación DSFinV-K.

💡Haz los timeouts configurables

Permite a los administradores ajustar los valores de timeout (p. ej., 1,5-5 segundos para transacciones) sin cambios de código. Esto ahorra ciclos de desarrollo y se adapta a condiciones de red variables.

Estrategia de reintento

Para errores transitorios (5xx, timeouts, límites de frecuencia), usa backoff exponencial:

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));
    }
  }
}

Árbol de decisión para la resolución de problemas

¿Tienes un error?
  │
  ├── 401 Unauthorized
  │     └── ¿Ha caducado tu token?
  │           ├── Sí → Vuelve a autenticarte con clave API + secreto
  │           └── No → Comprueba las credenciales en el HUB
  │
  ├── 400 Bad Request
  │     └── Comprueba el campo `message` para saber qué campo es inválido
  │           └── Valida tu payload JSON frente al esquema de la API
  │
  ├── 404 Not Found
  │     └── ¿Existe el recurso?
  │           ├── Comprueba que el ID es correcto (formato UUIDv4)
  │           └── Asegúrate de que el recurso fue creado en el entorno correcto (TEST vs LIVE)
  │
  ├── 409 Conflict
  │     └── El recurso ya existe o está siendo modificado
  │           └── Usa GET para comprobar el estado actual antes de reintentar
  │
  ├── 429 Rate Limited
  │     └── Espera con retraso exponencial
  │           └── Comprueba si te estás autenticando de nuevo en cada solicitud (no lo hagas)
  │
  └── Error 5xx del servidor
        └── Comprueba status.fiskaly.com
              ├── Incidente conocido → Espera la resolución
              └── Sin incidente → Reintenta con backoff exponencial; contacta con soporte si persiste

Estado del servicio

Monitoriza el estado del servicio fiskaly en status.fiskaly.com.

Errores comunes de integración

Estos son los errores que el soporte de fiskaly ve más a menudo de los equipos durante tu primera integración. Evitarlos ahorra tiempo de depuración significativo.

Error	Qué ocurre	Cómo evitarlo
Volver a autenticarse en cada solicitud	Errores de límite de frecuencia `429`; latencia innecesaria en cada pago	Almacena en caché el token de acceso (TTL 24h). Solo vuelve a autenticarte con `401`.
No guardar el `admin_puk`	No se puede establecer el PIN Admin en el TSS; bloqueado en estado `UNINITIALIZED`	Guarda el `admin_puk` de la respuesta de creación del TSS inmediatamente.
Reutilizar UUIDs	Errores `409 Conflict` al crear TSS, clientes o transacciones	Genera un nuevo UUIDv4 para cada llamada de creación de recursos.
Bloquear el pago ante un fallo de firma	Los clientes esperan indefinidamente si el TSS es lento o no está disponible	Establece un timeout de 3-5 segundos en la firma. Emite el recibo con “TSS no disponible” y reintenta más tarde.
Usar credenciales TEST en LIVE (o viceversa)	`401 Unauthorized` — las credenciales son específicas del entorno	Verifica que la URL base coincide con el entorno de la clave API. TEST y LIVE son completamente separados.
Saltarse la inicialización del TSS	`400 E_TSS_NOT_INITIALIZED` al crear clientes o transacciones	Sigue todos los pasos necesarios: crea el TSS, actualízalo a `UNINITIALIZED`, establece el PIN Admin, inicia sesión como Admin y cambia el TSS a `INITIALIZED`.
No manejar correctamente `tx_revision`	`422 E_TX_INVALID_STATE` o errores de transacción duplicada	Comienza con `tx_revision=1` (ACTIVE), termina con `tx_revision=2` (FINISHED). Siempre incrementa.
Sondeo síncrono de exportaciones	Timeouts en la generación de exportaciones DSFinV-K (puede tardar hasta 10 minutos)	Usa sondeo asíncrono: activa la exportación, luego sondea el endpoint de estado hasta que `state: COMPLETED`.
Hardcodear timeouts	El equipo de desarrollo no puede ajustarlos sin un release de código	Haz los timeouts configurables (p. ej., 1,5-5 segundos para transacciones). Ajustable por el administrador es lo ideal.

Recursos relacionados

Guía de gestión de errores

Mejores prácticas para el timeout y la recuperación de errores en SIGN DE

Errores de declaración

Códigos de error y códigos de estado específicos de SUBMIT DE

Referencia de API

Documentación completa de endpoints para todas las API de fiskaly

Was this page helpful?