Errors

Failed calculations never return status: "success" with a null or NaN result. Illegal inputs are HTTP 400 with status: "error". OpenAPI: ApiError.

HTTP status

Status	Meaning
200	Calculation succeeded
400	Invalid JSON or inputs the engine rejects (code, field, recoverable, suggestion)
404	Unknown id or capability (body lists acceptable ids when it can)
405	Unsupported method (GET catalog / POST calc / OPTIONS)
409	VERSION_MISMATCH — pinned calculation_version / CalculatorX-Spec-Version unavailable
415	Unsupported Content-Type (use application/json)
429	Rate limited (RATE_LIMITED + Retry-After)
500	Unexpected server error

CORS is open (Access-Control-Allow-Origin: *).

Error body

{
  "type": "https://www.calculatorx.com/problems/voltage-must-be-positive",
  "title": "Voltage must be greater than zero",
  "status": "error",
  "http_status": 400,
  "code": "VOLTAGE_MUST_BE_POSITIVE",
  "error": "Voltage must be greater than zero",
  "detail": "Voltage must be greater than zero",
  "field": "volts",
  "recoverable": true,
  "suggestion": "Provide a voltage greater than 0.",
  "invalid_parameters": [
    { "name": "inputs.volts", "constraint": "> 0" }
  ]
}

Treat code as the stable contract. error / detail are human-readable. recoverable: true means a corrected request can succeed.

JSON Schema for Agent-critical tools is a callable-input envelope (types, required fields, enums). Sending current = 0 may be schema-valid; the engine then returns CURRENT_MUST_BE_NONZERO. Domain semantics live in error codes, not in exclusiveMinimum.

Common codes:

Code	Typical cause
MISSING_REQUIRED_INPUT	Required field omitted
INVALID_NUMBER / INVALID_MODE	Wrong type or enum
VOLTAGE_MUST_BE_POSITIVE	Electrical domain constraint
CURRENT_MUST_BE_NONZERO	Watts path V=P/I with P>0 and I=0
RESISTANCE_MUST_BE_NONZERO	Ohms reverse I=V/R with V≠0 and R=0
UNDEFINED	Indeterminate form such as 0÷0
POWER_FACTOR_OUT_OF_RANGE	PF outside (0, 1] (explicit invalid PF, not a silent default)
POWER_FACTOR_IGNORED	Warning (not an error): REST DC payload included PF; engine ignored it. Canonical Agent schema forbids DC PF.
NON_FINITE_RESULT	IEEE-754 overflow / non-finite result
VERSION_MISMATCH	Pinned calculation version is not published
RATE_LIMITED	Per-IP window exceeded
ENGINE_NOT_FOUND / CAPABILITY_NOT_FOUND	Unknown REST id or MCP capability_id

Version mismatch

Pinning CalculatorX-Spec-Version or calculation_version against a version that is not published returns HTTP 409:

{
  "status": "error",
  "http_status": 409,
  "code": "VERSION_MISMATCH",
  "recoverable": true
}

See Versioning & trust.

Rate limits

Per IP, sliding window (beta, no API key):

Surface	Limit
REST POST /api/v1/calc/*	~60 / min
MCP RPC	~120 / min
MCP execute_calculation	~30 / min

Exceeded → HTTP 429 with code: "RATE_LIMITED", retry_after_seconds, and a Retry-After header.

{
  "type": "https://www.calculatorx.com/problems/rate-limited",
  "title": "Rate limit exceeded",
  "status": "error",
  "http_status": 429,
  "code": "RATE_LIMITED",
  "recoverable": true,
  "retry_after_seconds": 12,
  "limit": 60
}

Do not hammer the endpoint. There is no authentication or per-key quota yet.