Errores

La API de Emify usa códigos de estado HTTP estándar y devuelve un cuerpo JSON consistente cuando algo falla.

Códigos de estado

Código	Significado	Causa típica
`400 Bad Request`	Solicitud inválida	Parámetros incorrectos o faltantes, o cuerpo mal formado.
`401 Unauthorized`	No autenticado	Falta el header `X-Api-Key` o la clave es inválida.
`403 Forbidden`	Sin permiso	La clave no tiene acceso al recurso solicitado.
`404 Not Found`	No encontrado	El recurso no existe. Verifica la URL y los identificadores.
`422 Unprocessable Entity`	Regla de negocio	Los datos son válidos pero infringen una regla de negocio o del ente tributario. Al crear un comprobante solo responde así por `external_reference` duplicada o empresa sin certificado: el resto de las reglas registra el documento en `INV` (ver abajo).
`500 Internal Server Error`	Error del servidor	Error inesperado de Emify.
`502 Bad Gateway`	Fallo de un organismo externo	Un servicio del que Emify depende —por ejemplo el banco central al consultar un tipo de cambio— no respondió o devolvió algo inesperado. Es transitorio: se puede reintentar.

Formato de error

Las respuestas de error incluyen un cuerpo JSON con esta estructura:

{
  "error": "Bad Request",
  "code": "INVALID_REQUEST",
  "message": "El campo 'invoice_type' es requerido.",
  "details": ["invoice_type: must not be null"],
  "timestamp": "2026-01-15T10:30:00",
  "trace_id": "a1b2c3d4e5f6"
}

Campo	Descripción
`error`	Nombre del estado HTTP.
`code`	Código estable del error, para manejarlo de forma programática.
`message`	Descripción legible del error.
`details`	Lista de detalles, típicamente errores de validación por campo.
`timestamp`	Momento en que ocurrió el error.
`trace_id`	Identificador de la traza, útil para el equipo de soporte.

Maneja los errores por su code, no por el texto de message: el mensaje puede cambiar, el código no. Al reportar un problema a soporte, incluye el trace_id.

Errores de negocio al crear un comprobante

Al crear un comprobante, una regla de negocio incumplida —un total que no cuadra con los ítems, un código que no existe en los catálogos, un texto más largo que el que admite el ente tributario— no rechaza el request. El documento se registra y la respuesta es 201 con status: "INV" (inválido) y la lista validation_errors, con un elemento por regla:

{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "invoice_type": "FCE",
  "number": null,
  "status": "INV",
  "validation_errors": [
    {
      "field": "total",
      "code": "INVOICE_TOTALS_MISMATCH",
      "message": "El total del comprobante (40000.0) no coincide con el total calculado (39951.0): sub_total + totalTaxes - totalDiscount"
    }
  ]
}

Ese documento no se envía al ente tributario, no consume folio y no dispara webhook ni email. Queda visible en el portal y no se puede reintentar: para emitirlo, corrige el contenido y crea un documento nuevo. Puedes reusar el mismo external_reference, porque un documento en INV no lo retiene.

Un 201 no garantiza que el documento se vaya a emitir: revisa siempre el status de la respuesta.

Tres reglas siguen rechazando con 422, sin registrar nada ni consumir folio, aunque vengan junto a otras: DUPLICATE_EXTERNAL_REFERENCE (el external_reference ya es de otro documento vivo de la empresa), CERTIFICATE_NOT_FOUND (la empresa no tiene certificado activo) y CERTIFICATE_EXPIRED (el certificado activo de la empresa venció; el mensaje informa la fecha de vencimiento). Ante CERTIFICATE_EXPIRED, sube un certificado vigente y vuelve a enviar el mismo cuerpo. La reemisión de un documento rechazado tampoco cambia: cualquier regla incumplida responde 422 con code: VALIDATION_ERROR y una línea <campo>: <mensaje> por cada falla en details. Las tablas que siguen listan el code de cada regla, el que llega en validation_errors.

Impuestos

Al crear cualquier comprobante, estas reglas lo registran en INV con el code en validation_errors. En la reemisión responden 422 con code: VALIDATION_ERROR y, en details, una línea <campo>: <mensaje> por cada falla.

Regla	Qué lo causa
`TAX_RATE_REQUIRED`	El impuesto no trae `rate`, y su tipo no la toma del catálogo: es `rate_source: CLIENT`, o no existe en el catálogo del país. Ver la tasa de cada impuesto.
`INACTIVE_TAX_TYPE`	El `type` del impuesto existe en el catálogo del país pero está dado de baja: ya no aparece en `GET /api/tax-types`. Aplica a `items[].taxes`, `global_taxes` y `totals.taxes`. Ver la tasa de cada impuesto.
`ITEM_MULTIPLE_VAT_TAXES`	Chile, en factura, nota de crédito o nota de débito: el ítem lleva más de un impuesto de IVA. Es gravado o es exento.
`MULTIPLE_VAT_RATES`	Chile, en los mismos documentos: los ítems gravados tienen tasas de IVA distintas. El documento declara una sola.
`TAXED_INVOICE_WITHOUT_TAXED_ITEMS`	Chile, en factura (`FCE`): todos los ítems son exentos. El SII rechaza una factura afecta sin monto neto; si todo es exento, emite una factura exenta (`FCEE`).

Retenciones de la factura de compra (Chile)

Reglas de la retención de IVA en la factura de compra (FCO) y en las notas que la referencian. Como las de impuestos, registran el documento en INV, y en la reemisión responden 422.

`code`	Qué lo causa
`RETENTION_NOT_ALLOWED_FOR_DOCUMENT_TYPE`	Un ítem lleva una retención en un documento que no es una `FCO` ni una nota que referencia una.
`ITEM_RETENTION_REQUIRED`	Un ítem gravado de una `FCO`, o de una nota que referencia una, no lleva retención.
`ITEM_MULTIPLE_RETENTIONS`	El ítem lleva más de una retención.
`ITEM_RETENTION_ON_EXEMPT_LINE`	El ítem es exento (`CL_EX_IVA`) y lleva retención: no hay IVA que retener.
`RETENTION_TAX_ONLY_IN_ITEMS`	La retención aparece en `totals.taxes` o en `global_taxes`. Se declara solo en `items[].taxes`.
`RETENTION_RATE_OUT_OF_RANGE`	La tasa de una retención parcial no es mayor que 0 o no es menor que el IVA del ítem. Una retención del 100 % se declara con un tipo de retención total.
`MULTIPLE_RETENTION_RATES`	Dos ítems con el mismo tipo de retención declaran tasas distintas.
`ITEM_CPCS_CODE_REQUIRED`	Un ítem con retención por cambio de sujeto (cualquier tipo salvo `CL_IVA_RET`) no trae `code` de tipo `cpcs`.
`ITEM_CPCS_CODE_MISMATCH`	El código `cpcs` es de otra familia de productos: sus dos primeros dígitos no son los del código de la retención.
`ITEM_REFERENCE_QUANTITY_REQUIRED`	Un ítem con `CL_RET_GAN` no trae `reference_quantity` mayor que 0 (las cabezas de ganado).
`REFERENCE_QUANTITY_NOT_ALLOWED`	Un ítem sin retención de ganado trae `reference_quantity`.
`RETENTION_GLOBAL_DISCOUNT_NOT_SUPPORTED`	Una `FCO`, o una nota que referencia una, trae `totals.discount`. Aplica el descuento en los ítems.

Montos de la boleta (Chile)

Emify no modifica el neto, el IVA ni el total de una boleta afecta. Si no se pueden informar al SII tal como los enviaste, la creación responde 201 con status: "INV" y este code en validation_errors, sobre el campo totals: el documento no consume folio ni se envía al SII. El message dice qué neto, IVA y total aceptaría el SII con tus líneas tal como llegaron, en cada una de sus dos formas de informar el detalle (con IVA incluido o en neto). En la reemisión responde 422.

`code`	Qué lo causa
`INVOICE_DTE_TOTALS_INCONSISTENT`	El neto, el IVA o el total traen centavos; las líneas no suman ni el total (con IVA incluido) ni el neto (en neto); o el IVA no es el 19 % del neto. El caso más común es una línea que termina en ,50 (11.160,5) con el neto redondeado hacia abajo (11.160): el SII redondea esa línea hacia arriba. Ver Montos e IVA en la boleta.

Comprobantes argentinos Clase A y B

Al crear una Factura, Nota de Débito o Nota de Crédito A o B, estas reglas se validan antes de enviar el comprobante a ARCA. Si alguna falla, el comprobante queda en INV con el code y el campo afectado en validation_errors, y no se envía a ARCA:

`code`	Qué lo causa
`ISSUER_TAX_CONDITION_NOT_VALID_FOR_DOCUMENT_TYPE`	La empresa emisora no es Responsable Inscripto, o el request declara al emisor con otra condición.
`RECIPIENT_TAX_CONDITION_NOT_VALID_FOR_DOCUMENT_TYPE`	La condición frente al IVA del receptor no corresponde a la clase: la A es para RI y monotributistas, la B para el resto.
`RECIPIENT_DOCUMENT_TYPE_NOT_VALID_FOR_DOCUMENT_TYPE`	En la Clase A, el receptor no está identificado con CUIT.
`ITEM_VAT_TREATMENT_REQUIRED`	El ítem no lleva exactamente un impuesto de IVA.
`ITEM_VAT_AMOUNT_MISMATCH`	El IVA del ítem no es neto × alícuota (±0,01), o un exento o no gravado trae importe.
`INVALID_GLOBAL_TAX_TYPE`	El tributo de `global_taxes` no existe o es IVA, que va por ítem.
`INVALID_GLOBAL_TAX`	El tributo no tiene base imponible o alícuota válida, o `AR_OTROS_TRIB` viene sin `description`.
`GLOBAL_DISCOUNT_NOT_SUPPORTED`	Hay un descuento global: aplícalo por ítem.
`INVOICE_COMPOSITION_MISMATCH`	`sub_total` o `total` no cierran contra los ítems y los tributos. El mensaje indica el valor esperado.
`BILLING_REFERENCE_CLASS_MISMATCH`	La nota referencia un comprobante de otra letra.
`INVALID_ISSUER_CBU`	`issuer.tax_information.cbu` no tiene 22 dígitos o tiene un dígito verificador incorrecto.
`ISSUER_PAYMENT_MODALITIES_EXCLUSIVE`	El request declara `cbu` y `subject_to_retention: true` a la vez: son modalidades excluyentes.
`ISSUER_PAYMENT_MODALITY_NOT_VALID_FOR_DOCUMENT_TYPE`	`cbu` o `subject_to_retention` en un comprobante que no es Clase A.

Comprobantes argentinos en moneda extranjera

Valen para cualquier clase (A, B o C). Si alguna falla, el comprobante queda en INV con currency.exchange_rate en validation_errors:

`code`	Qué lo causa
`EXCHANGE_RATE_REQUIRED_FOR_FOREIGN_CURRENCY`	El comprobante está en una moneda extranjera y `currency.exchange_rate` falta o vale 1.
`EXCHANGE_RATE_MUST_BE_ONE_FOR_LOCAL_CURRENCY`	El comprobante está en pesos y `currency.exchange_rate` es distinta de 1.

Buenas prácticas

Reintenta las respuestas 5xx con backoff exponencial. El 502 señala un organismo externo caído, no un dato incorrecto: la misma petición suele funcionar más tarde.
No reintentes las respuestas 4xx sin corregir la petición: el resultado será el mismo.
Registra el trace_id y el identificador del recurso junto con la respuesta de error para facilitar el diagnóstico.

Primeros pasos

Conceptos

Códigos de estado

Formato de error

Errores de negocio al crear un comprobante

Impuestos

Retenciones de la factura de compra (Chile)

Montos de la boleta (Chile)

Comprobantes argentinos Clase A y B

Comprobantes argentinos en moneda extranjera

Buenas prácticas

​Códigos de estado

​Formato de error

​Errores de negocio al crear un comprobante

​Impuestos

​Retenciones de la factura de compra (Chile)

​Montos de la boleta (Chile)

​Comprobantes argentinos Clase A y B

​Comprobantes argentinos en moneda extranjera

​Buenas prácticas

Códigos de estado

Formato de error

Errores de negocio al crear un comprobante

Impuestos

Retenciones de la factura de compra (Chile)

Montos de la boleta (Chile)

Comprobantes argentinos Clase A y B

Comprobantes argentinos en moneda extranjera

Buenas prácticas