Warnings

Every calculation response carries a warnings array. It is the channel through which the engine says “what you sent me does not line up with what I can see” — without deciding on your behalf.

A warning never changes an amount. Every figure in the response already reflects the request exactly as you sent it.

That is what separates this channel from validation. A warning reports that an input contradicts something the engine can check for itself, and leaves the decision to you — because you may hold information this API never receives.

The field

warnings is always present and never null. It is an empty list when there is nothing to flag, so you can iterate it without branching. It appears on the /calculate response and inside every results[].calculation of a /batch response.

{
  "warnings": [
    {
      "code": "FLAG_THRESHOLD_MISMATCH",
      "field": "overrides.aplica_auxilio_transporte",
      "message": "aplica_auxilio_transporte=true pero el salario basico (8,754,525) supera el umbral legal de 2 SMMLV (3,501,810). El auxilio se pago igual, por decision del integrador.",
      "severity": "warning"
    }
  ]
}

Field	Description
`code`	Stable code. Branch on this, not on the message text
`field`	Dotted path of the request field the warning is about
`message`	Human-readable explanation, quoting the values compared and the legal basis
`severity`	Always `warning` in v1

severity exists from the start so that richer severities will not break the contract later.

Warning codes

Code	What it means
`FLAG_THRESHOLD_MISMATCH`	A boolean flag contradicts the salary threshold of the benefit it enables. The calculation honoured the flag anyway
`PERIOD_DAYS_IGNORED`	`period.days` played no part in a `split_monthly` settlement — the factor came from `period.type`. The amounts are half a monthly salary
`SALARY_FIELDS_DISAGREE`	Both `daily_salary` and `monthly_salary` arrived and they contradict each other. The daily figure was used, being the legal base unit
`EVENT_PAYMENT_SPLIT`	The period split a concept whose payment the law fixes to a date, not to a stretch of the month — Brazil’s 13th and ferias, Peru’s gratificacion

The last three came in with fortnightly settlement.

Threshold rules (CO ordinario)

Two Colombian flags are checked against the salary that gates them:

Flag	Threshold	Basis
`aplica_auxilio_transporte`	`<= 2 SMMLV` (inclusive)	Ley 15/1959
`aplica_exoneracion_114_1`	`< 10 SMMLV` (exclusive)	ET Art. 114-1

Both are measured on salario_basico, not on total earnings. That is a debatable reading, so every message states exactly what it compared: a payroll officer who disagrees can see the criterion instead of guessing it. What the silence used to cost, measured in CO 2026:

Auxilio paid where it was not due, at 5 SMMLV: 249,095 per month of overpayment per employee, plus an inflated cesantias base.
Exoneration claimed where it was not due, at 15 SMMLV: 3,545,583 per month the employer believes it does not owe. Over twelve months, more than 42 million of exposure with the UGPP and the DIAN.

Why one flag warns in both directions and the other does not

aplica_exoneracion_114_1 does not warn when it is off, and that is deliberate. The exoneration also requires the employer to be a corporate income tax filer — an attribute of the company that never arrives in a request. Warning on the off case would fire on almost every legitimate ordinary request, and that is how you train an integrator to ignore the entire channel. The auxilio warns in both directions, because there the engine has all the information it needs. The same reasoning applies in Peru: of the two concepts paid alongside the gratificacion, only one is registered. Two warnings for one problem is the same mistake.

Handling warnings in code

import httpx

result = httpx.post(
    "https://api.clevis.dev/v1/payroll/calculate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json=payload,
).json()

for warning in result["warnings"]:
    log.warning(
        "payroll warning %s on %s: %s",
        warning["code"], warning["field"], warning["message"],
    )

const result = await fetch("https://api.clevis.dev/v1/payroll/calculate", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
}).then((r) => r.json());

for (const warning of result.warnings) {
  console.warn(`${warning.code} on ${warning.field}: ${warning.message}`);
}

Surface warnings to whoever reviews the payroll before it is released. They are cheapest to act on there.

What warnings are not

Not a legal validation. Clevis does not say whether the employer is entitled to a benefit. It says the flag and the salary do not agree.Not a complete list of what could be wrong. Registered rules exist only for CO ordinario and for the four codes above. There is no general coverage to promise.Not a rejection. Nothing is refused — not even the case that hurts most legally, an auxilio omitted for someone entitled to it.

Get Started

Countries

Calculations

Payouts

Guides

The field

Warning codes

Threshold rules (CO ordinario)

Why one flag warns in both directions and the other does not

Handling warnings in code

What warnings are not

​The field

​Warning codes

​Threshold rules (CO ordinario)

​Why one flag warns in both directions and the other does not

​Handling warnings in code

​What warnings are not

The field

Warning codes

Threshold rules (CO ordinario)

Why one flag warns in both directions and the other does not

Handling warnings in code

What warnings are not