ERROR MODEL

Machine-readable failures are part of the public contract

MCP-AQL uses a discriminated success/error envelope and a structured error object so clients can distinguish validation problems, missing resources, permissions, and server failures without parsing free-form text.

Error Codes Spec Issue #199

On this page

Jump to a section

Use the outline to move through longer pages without losing your place.

  1. Canonical response envelope
  2. MVP error code registry
  3. Why the code field matters
  4. Concrete error examples
  5. Client handling guidance
  6. How adapter-specific failures map in
  7. Current draft focus

Related reading

Canonical response envelope

Success

{
  "success": true,
  "data": { ... }
}

Failure

{
  "success": false,
  "error": {
    "code": "VALIDATION_MISSING_PARAM",
    "message": "Missing required parameter 'owner'"
  }
}

MVP error code registry

Code Category Meaning
VALIDATION_MISSING_PARAM Validation Required parameter not provided
VALIDATION_INVALID_TYPE Validation Parameter value does not match the expected type
VALIDATION_UNKNOWN_PARAM Validation Request contains a parameter outside the declared schema
NOT_FOUND_OPERATION Not Found Requested operation does not exist
NOT_FOUND_RESOURCE Not Found Target resource does not exist
PERMISSION_DENIED Permission Caller lacks the required authorization
CONFIRMATION_REQUIRED Permission Operation is denied pending explicit confirmation
INTERNAL_ERROR Internal Unexpected server or adapter failure

Why the code field matters

  • LLMs and client code can tell "fix your request" failures from "server-side problem" failures.
  • Adapters can map target-system failures into a predictable registry.
  • Monitoring and analytics can group failures by category instead of message text.
  • Localized or rewritten human messages do not break programmatic recovery.

Concrete error examples

Validation error

{
  "success": false,
  "error": {
    "code": "VALIDATION_MISSING_PARAM",
    "message": "Missing required parameter 'owner'",
    "details": {
      "param_name": "owner"
    }
  }
}

Not-found error

{
  "success": false,
  "error": {
    "code": "NOT_FOUND_RESOURCE",
    "message": "Repository 'acme/widgets' not found",
    "details": {
      "resource_type": "repository",
      "resource_id": "acme/widgets"
    }
  }
}

Permission error

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Operation 'delete_user' is not allowed for this caller",
    "details": {
      "operation": "delete_user"
    }
  }
}

Internal error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected adapter failure",
    "details": {
      "request_id": "req_7f1d"
    }
  }
}

Client handling guidance

Branch on error.code

Use the code for programmatic behavior: retry policy, UI state, escalation path, and whether a client should fix the request or stop execution entirely.

  • VALIDATION_*: repair the request
  • NOT_FOUND_*: stop or ask the user to choose another target
  • PERMISSION_*: request credentials or confirmation
  • INTERNAL_*: surface a server-side fault and preserve request context

Display error.message to humans

The message is for logs, dashboards, and human-visible explanations. It can be localized or rewritten without breaking the client's recovery logic because the recovery key is the code.

How adapter-specific failures map in

Adapters do not expose raw target-system failures as their public contract. They translate them into the MCP-AQL registry and preserve target-specific context in error.details when it helps recovery.

  • Target API 404s should map to NOT_FOUND_RESOURCE
  • Target permission failures should map to PERMISSION_DENIED or CONFIRMATION_REQUIRED
  • Unexpected downstream failures should map to INTERNAL_ERROR with request context preserved in details

Current draft focus

Defined today

  • Structured error.code and error.message fields
  • MVP registry with validation, not-found, permission, and internal categories
  • Optional details object for additional context

Still being aligned

  • Implementation surfaces that still emit string-only failures
  • Exact schema and prose alignment across all response definitions
  • Conformance checks that validate machine-readable error surfacing

Live spec issue #199 tracks the remaining alignment work between the error-code registry, response envelope requirements, and implementation-facing schemas.