Skip to main content

​
What it means

The request reached the tool handler but was rejected before doing any work. Either the arguments did not match the tool’s declared input schema (wrong type, missing required field, unknown enum) or a business rule inside the handler rejected the payload (cross-organisation reference, mutually exclusive fields). Retrying the same payload will fail identically. The caller must correct the input first.

​
How to fix

  • Walk details.errors[]; each row names the offending field, a stable machine code, and a human-safe message.
  • If your LLM constructed the arguments, feed the field-level errors back to it so it can fix and re-call.
  • If the schema is unclear, check the tool’s inputSchema from tools/list output.

​
Response envelope

{
  "ok": false,
  "error_envelope": {
    "code": "INVALID_INPUT",
    "message": "Input failed validation.",
    "docs_url": "https://tryaeris.ai/docs/mcp/errors/invalid-input",
    "retryable": false,
    "retry_after_ms": null,
    "details": {
      "errors": [
        { "field": "date_range.end", "code": "before_start", "message": "end must be on or after start" }
      ]
    }
  }
}
  • IDEMPOTENCY_REQUIRED — same 422, but specifically about a missing idempotency_key.
  • NOT_FOUND — when the input is well-formed but references something that does not exist.