Referencia global de errores

Listado de códigos HTTP y error.code que puede devolver la API. Todas las respuestas de error tienen success: false y un objeto error con code, message y opcionalmente details.

Formato de respuesta de error

Ejemplo con details (validación de campos):

{
  "success": false,
  "error": {
    "code": "INCONSISTENT_TOTALS",
    "message": "One or more provided values do not match the computed values.",
    "details": [
      { "field": "payments[].amount (sum)", "provided": 11, "expected": 11.5 }
    ]
  }
}

Ejemplo sin details (error genérico):

{
  "success": false,
  "error": {
    "code": "TX_LIMIT_REACHED",
    "message": "Transaction limit reached"
  }
}

Tabla de códigos HTTP y error.code

HTTP	error.code	Descripción
400	`DOCUMENT_NOT_FOUND`	Documento no encontrado o no pertenece a la empresa.
400	`DOCUMENT_NOT_ELIGIBLE`	Documento no elegible para la operación solicitada.
400	`INVALID_ACCESS_KEY`	Clave de acceso con formato incorrecto (≠ 49 dígitos).
400	`INVALID_DOCUMENT_NUMBER`	Número de comprobante con formato incorrecto.
400	`INVALID_PARAMS`	Query params inválidos (ej. faltan o sobran en detail).
400	`INVALID_XML_TYPE`	`type` no es unsigned, signed o authorized.
400	`RIDE_NOT_AVAILABLE`	El RIDE solo está disponible para documentos AUTHORIZED.
400	`XML_NOT_AVAILABLE`	Ese XML aún no está disponible.
400	`EVENTS_REQUIRED`	Array events vacío.
400	`INVALID_EVENTS`	Eventos no válidos en el array de webhook.
400	`WEBHOOK_TEST_FAILED`	No se pudo conectar a la URL del webhook en la prueba.
401	`API_KEY_REQUIRED`	Headers X-API-Key o X-API-Secret ausentes.
401	`INVALID_API_KEY`	API Key o Secret inválidos.
402	`TX_LIMIT_REACHED`	Límite de transacciones del plan alcanzado.
404	`WEBHOOK_ENDPOINT_NOT_FOUND`	Endpoint de webhook no encontrado.
422	`BUYER_ID_MISMATCH`	buyerId de la NC no coincide con la factura original.
422	`BUYER_ID_TYPE_MISMATCH`	buyerIdType de la NC no coincide con la factura original.
422	`BUYER_NAME_MISMATCH`	buyerName de la NC no coincide con la factura original.
422	`DISCOUNT_EXCEEDS_SUBTOTAL`	Descuento mayor que quantity × unitPrice en un ítem.
422	`DUPLICATE_LINE_INDEX`	lineIndex repetido en lines del partial-refund.
422	`DUPLICATE_TAX_ENTRY`	taxCode + rateCode duplicado en un ítem.
422	`FUTURE_ISSUE_DATE`	issueDate es una fecha futura.
422	`INCONSISTENT_TOTALS`	Algún total enviado no coincide con el calculado (±0.01).
422	`INVALID_BUYER_ID`	Formato de RUC, cédula o consumidor final incorrecto.
422	`INVALID_IVA_RATE_CODE`	rateCode de IVA no válido.
422	`INVALID_LINE_INDEX`	lineIndex fuera de rango en partial-refund.
422	`INVALID_LINE_REFERENCE`	Línea en partial-refund sin lineIndex ni mainCode.
422	`IVA_ZERO_CONSUMIDOR_FINAL`	IVA 0% con buyerIdType "07" (Consumidor Final).
422	`LINE_NOT_FOUND`	mainCode no encontrado en la factura original.
422	`MISSING_RATE`	rate ausente en ICE o IRBPNR.
422	`MISSING_TAX_BASE`	taxableBase ausente en ICE o IRBPNR.
422	`MISSING_TERM_UNIT`	termUnit ausente cuando termDays > 0.
422	`ORIGINAL_DOCUMENT_NOT_AUTHORIZED`	Factura original no está AUTHORIZED.
422	`ORIGINAL_DOCUMENT_NOT_FOUND`	Factura original no encontrada.
422	`QUANTITY_EXCEEDS_ORIGINAL`	Quantity mayor que la cantidad original de la línea.
422	`QUANTITY_INVALID`	quantity ≤ 0 en partial-refund.
503	`RIDE_SERVICE_ERROR`	Error del servicio de generación de RIDE PDF.