Error Handling

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "SCHEME_NOT_FOUND",
    "message": "No scheme 'ordinario' found for country 'BR' year 2025",
    "details": {},
    "request_id": "01HX9B2KM3..."
  }
}

Use the code field for programmatic error handling, not the HTTP status code. Include the request_id when contacting support to help trace your request.

Error codes

Error codes are stable API surface. Branch on code, not on the HTTP status.

Authentication

Code	HTTP	When
`MISSING_AUTH_TOKEN`	401	No `Authorization` header provided
`INVALID_API_KEY`	401	The key is unknown or has been revoked
`API_KEY_WRONG_ENVIRONMENT`	401	A sandbox key was used against production, or vice versa

See Authentication for the key format and rotation.

Request validation

Code	HTTP	When
`VALIDATION_ERROR`	422	Request body failed validation. `details` carries the field path
`SCHEME_NOT_FOUND`	404	Country/scheme/year combination not loaded
`PERIOD_TYPE_NOT_SUPPORTED`	422	The scheme does not liquidate that `period.type`
`REFERENCE_VALUE_NOT_FOUND`	422	Reference value (UMA, SMMLV, UTM) not available for the requested date
`SUPERSEDES_MISMATCH`	422	`options.supersedes` points at a calculation for a different employee, employer or period

VALIDATION_ERROR reports the exact field path. For a single calculation that is employee.risk_class_rate; in a batch it is employees.{i}.risk_class_rate, which is the only thing that is actionable in a batch of 500.

risk_class_rate is required for MX, CO, AR and CL, and has no default. Omitting it returns 422 VALIDATION_ERROR. A batch is rejected whole — schema validation happens before any row runs.

PERIOD_TYPE_NOT_SUPPORTED returns structured details so you can branch on data rather than on prose:

{
  "error": {
    "code": "PERIOD_TYPE_NOT_SUPPORTED",
    "message": "Scheme 'ordinario' for CO 2026 does not support period type 'weekly'",
    "details": {
      "country": "CO",
      "scheme": "ordinario",
      "year": 2026,
      "period_type": "weekly",
      "supported_period_types": ["monthly", "biweekly"]
    },
    "request_id": "01HX9B2KM3..."
  }
}

A batch with an unsupported period.type fails whole, not row by row: a period no row can liquidate is not a single row’s error. See Pay periods.

Calculation

Code	HTTP	When
`FORMULA_EVALUATION_ERROR`	422	Runtime formula failure (e.g., division by zero)
`CIRCULAR_DEPENDENCY`	422	Cycle detected in concept dependencies

Retrieval

Code	HTTP	When
`CALCULATION_NOT_FOUND`	404	No calculation with that id is visible to your client
`BATCH_NOT_FOUND`	404	No batch with that id is visible to your client
`EMPLOYER_NOT_FOUND`	404	No employer with that id is visible to your client
`EMPLOYEE_NOT_FOUND`	404	No employee with that id under that employer

A resource belonging to another client returns 404, never 403. Clevis does not reveal that a record it will not show you exists.

Availability

Code	HTTP	When
`PERSISTENCE_UNAVAILABLE`	503	The calculation could not be recorded, so it was not returned
`INTERNAL_ERROR`	500	Unexpected server error

PERSISTENCE_UNAVAILABLE means exactly what it says: the calculation was not stored, and therefore no id and no amounts were returned. This is deliberate. Handing back an id that nothing can ever fetch is the defect stored calculations exist to fix. Retry with the same Idempotency-Key. /v1/payroll/simulate and /v1/payroll/schemes do not depend on storage and are not affected.

There is no RATE_LIMIT_EXCEEDED and no 429. Earlier versions of this page listed one; rate limiting is not implemented.

Payouts

Payout error codes are documented separately in Payout errors.

Warnings are not errors

A successful calculation can still carry a warnings array. A warning never changes an amount and never changes the status code — it reports that an input contradicts something the engine can check for itself. See Warnings.

Handling errors in code

import httpx

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

if response.status_code != 200:
    error = response.json()["error"]
    match error["code"]:
        case "SCHEME_NOT_FOUND":
            print(f"Scheme not available: {error['message']}")
        case "VALIDATION_ERROR":
            print(f"Invalid request: {error['details']}")
        case "PERSISTENCE_UNAVAILABLE":
            print("Not stored, so not returned — retry with the same Idempotency-Key")
        case _:
            print(f"Error {error['code']}: {error['message']}")
            print(f"Request ID: {error['request_id']}")

const response = 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),
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case "SCHEME_NOT_FOUND":
      console.log(`Scheme not available: ${error.message}`);
      break;
    case "VALIDATION_ERROR":
      console.log("Invalid request:", error.details);
      break;
    case "PERSISTENCE_UNAVAILABLE":
      console.log("Not stored, so not returned — retry with the same Idempotency-Key");
      break;
    default:
      console.log(`Error ${error.code}: ${error.message}`);
      console.log(`Request ID: ${error.request_id}`);
  }
}

Batch error handling

In batch requests, individual employee errors do not abort the entire batch (unless fail_fast: true). Each employee result includes its own status:

{
  "results": [
    {
      "employee_id": "emp_001",
      "status": "success",
      "calculation": { ... }
    },
    {
      "employee_id": "emp_002",
      "status": "error",
      "error": {
        "code": "FORMULA_EVALUATION_ERROR",
        "message": "Division by zero in concept 'isr'"
      }
    }
  ],
  "total_succeeded": 1,
  "total_failed": 1
}

Set "fail_fast": true in batch options to abort on the first error instead.

Get Started

Countries

Calculations

Payouts

Guides

Error codes

Authentication

Request validation

Calculation

Retrieval

Availability

Payouts

Warnings are not errors

Handling errors in code

Batch error handling

​Error codes

​Authentication

​Request validation

​Calculation

​Retrieval

​Availability

​Payouts

​Warnings are not errors

​Handling errors in code

​Batch error handling

Error codes

Authentication

Request validation

Calculation

Retrieval

Availability

Payouts

Warnings are not errors

Handling errors in code

Batch error handling