API Reference

Error codes.

Every error response carries a machine-readable "code" in addition to a human "message". Branch on the code; show users the message.

Codes

VALIDATION_ERROR400Input failed validation. `field` points at the offending key (e.g. "current_a").
MISSING_FIELD400A required field was absent from the body. `field` names it.
UNAUTHORIZED401Missing, malformed, or revoked Bearer token.
FORBIDDEN403Authenticated but plan does not include this resource.
TOOL_NOT_FOUND404No tool at this {domain}/{slug}. Check /v1/tools for the catalog.
UNPROCESSABLE422Inputs were valid types but the tool's formula can't compute on them.
RATE_LIMITED429Per-minute or per-month limit hit. See Retry-After.
INTERNAL500Unexpected server fault. Use `meta.request_id` when contacting support.

Example error

400 Bad Request
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "\"current_a\" must be >= 0.001.",
    "field": "current_a"
  },
  "meta": { "request_id": "req_yXXl4h3hCrE" }
}

Handling tips

  • Always check ok first. Don't rely on HTTP status alone — proxies sometimes rewrite.
  • For VALIDATION_ERROR / MISSING_FIELD, render the message next to the named field in your UI.
  • For RATE_LIMITED, see Rate Limits for the retry contract.
  • For INTERNAL, retry once after a jittered delay. If it persists, file an issue with the request_id.