Documentation sections

Return Loss Measurement Error Calculator

POSThttps://rftools.io/api/py/v1/calculate

Slug return-loss-error. Calculate return loss measurement uncertainty from coupler directivity and source match. Determine worst-case error bounds for VNA testing. Free, instant results.

Inputs

Send every one of these in inputs, in the units shown. Most are required: a call without one is refused (400) and costs nothing; one the calculator can do without takes the default shown. An input outside its range is still computed and flagged in the provenance.

Inputs of return-loss-error
Name	Unit	Range	Default	Description
dutReturnLossnumber	dB	0 … 60	20	Return loss of the device under test
directivitynumber	dB	10 … 60	35	Directivity of the directional coupler or bridge used for the measurement
sourceMatchnumber	dB	10 … 60	30	Return loss of the measurement source port (how well the source is matched)
targetUncertaintynumber	dB	0.01 … 30	3	The largest return loss uncertainty the measurement may have. The status fails above 6 dB.

Outputs

Returned in values, by key. A value that is unbounded or undefined is null.

Outputs of return-loss-error
Field	Unit	Description
rlMax	dB	Highest return loss you might measure (errors cancel)
rlMin	dB	Lowest return loss you might measure (errors add)
uncertaintyDbheadline	dB	Measurement Uncertainty
dirError	dB	Error from coupler directivity only

Calling it

Calculate: one call, the request and response in full, and its errors.
Batch: this calculator with others, or a sweep, in one request.
Solve for a target: the value of one input that brings an output to a target.

curl -X POST https://rftools.io/api/py/v1/calculate \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "return-loss-error",
    "inputs": {
      "dutReturnLoss": 20,
      "directivity": 35,
      "sourceMatch": 30,
      "targetUncertainty": 3
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

result = client.calculate("return-loss-error", {
    "dutReturnLoss": 20,
    "directivity": 35,
    "sourceMatch": 30,
    "targetUncertainty": 3,
})
print(result.values)
print(result.warnings, result.provenance.formula_ref)

const response = await fetch("https://rftools.io/api/py/v1/calculate", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "slug": "return-loss-error",
    "inputs": {
      "dutReturnLoss": 20,
      "directivity": 35,
      "sourceMatch": 30,
      "targetUncertainty": 3
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "slug": "return-loss-error",
	  "inputs": {
	    "dutReturnLoss": 20,
	    "directivity": 35,
	    "sourceMatch": 30,
	    "targetUncertainty": 3
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/calculate", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

application/json

{
  "slug": "return-loss-error",
  "values": {
    "rlMax": 21.73421822963028,
    "rlMin": 18.55507398672743,
    "uncertaintyDb": 3.1791442429028507,
    "dirError": 1.421637052990647
  },
  "warnings": [],
  "errors": [],
  "provenance": {
    "method": "calculator:return-loss-error",
    "version": "api@3f2c1a9b04de",
    "formulaRef": "Agilent AN 1287-3: Applying Error Correction to VNA Measurements",
    "assumptions": [],
    "validRange": {
      "status": "inside",
      "bounds": {
        "dutReturnLoss": {
          "min": 0,
          "max": 60,
          "unit": "dB"
        },
        "directivity": {
          "min": 10,
          "max": 60,
          "unit": "dB"
        },
        "sourceMatch": {
          "min": 10,
          "max": 60,
          "unit": "dB"
        },
        "targetUncertainty": {
          "min": 0.01,
          "max": 30,
          "unit": "dB"
        }
      },
      "outside": [],
      "model": null
    },
    "computedAt": "2026-09-24T14:05:11.003Z",
    "inputs": {
      "dutReturnLoss": 20,
      "directivity": 35,
      "sourceMatch": 30,
      "targetUncertainty": 3
    },
    "seed": null,
    "elapsedSeconds": 0.003
  }
}

{
  "detail": [
    {
      "type": "float_parsing",
      "loc": [
        "body",
        "inputs",
        "dutReturnLoss"
      ],
      "msg": "Input should be a valid number, unable to parse string as a number",
      "input": "abc"
    }
  ]
}

An input sent as text. Nothing was counted.

{
  "detail": "More than 120 requests in 60 seconds from this address.",
  "errorKind": "rate_limited",
  "limit": 120,
  "windowSeconds": 60,
  "upgradeUrl": "https://rftools.io/pricing/"
}

Too many requests in a minute, with Retry-After.

Same inputs on the calculator pageReturn Loss Measurement Error Calculator, at these values