SmartRepair & Error Codes

Structured error responses with repair instructions — so agents can self-correct.

Overview

The gateway never returns raw stack traces or cryptic HTTP errors. Every error is wrapped in a structured RepairResult containing:

message: A clear, human-readable explanation
remedy: Actionable instructions for the agent to self-correct
_DEBUG_ECHO: A forensic payload showing the exact request data (method, URL, parameters)

Error Examples

Namespace Called Instead of Action

When an agent tries to execute a landmark namespace directly (e.g., call_action(action="repos") instead of a specific tool):

json

{
  "status": "error",
  "_PROTOCOL_ERROR": "STRUCTURAL_ERROR",
  "message": "You called 'repos', but that is a functional area (Landmark), not an executable tool.",
  "remedy": "Use 'inspect_landmark(landmark_id=\"repos\")' to discover available actions."
}

Missing Required Parameters

json

{
  "status": "error",
  "_PROTOCOL_ERROR": "VALIDATION_FAILED",
  "message": "Missing required parameters: ['sector_id']",
  "remedy": "The tool requires these fields: ['sector_id']. Check technical signatures with 'inspect_landmark'.",
  "example": "call_action(action='status_summary', parameters={'sector_id': 'VALUE'})"
}

Fuzzy Matching on Typos

When an action ID is not found, the engine performs a fuzzy search (Levenshtein distance) and suggests the closest matches.

Complete Protocol Error Codes

Code	HTTP Equivalent	Description
`PROTOCOL_VIOLATION`	—	Agent attempted action before completing the handshake
`ACCESS_DENIED`	403	Blocked by Security Policy or remote API
`AUTHENTICATION_FAILED`	401	Missing or invalid API credentials
`NOT_FOUND`	404	Action or resource not found
`VALIDATION_FAILED`	422	Missing required parameters (caught locally)
`BAD_REQUEST`	400	Malformed request to the remote API
`RATE_LIMIT_EXCEEDED`	429	API rate limit hit
`SERVER_ERROR`	500	Remote API internal server error
`REMOTE_ERROR`	Other	Unmapped HTTP error from the remote API
`PIPING_FAILED`	—	Data piping reference could not be resolved
`GRAPHQL_ERROR`	—	GraphQL-specific query error
`NESTING_REQUIRED`	—	GraphQL field requires sub-field selection
`TYPE_MISMATCH`	—	GraphQL variable type does not match schema

Automatic Remote Error Translation

HTTP errors from the target API are automatically translated into structured Elemm errors:

json

{
  "status": "error",
  "_PROTOCOL_ERROR": "RATE_LIMIT_EXCEEDED",
  "message": "Remote server returned rate limit error (HTTP 429).",
  "remedy": "The remote system is throttled. Implement a delay or backoff before retrying."
}

💡 TIP

When running in a sequence, the sequencer can use retryOn: ["RATE_LIMIT_EXCEEDED"] to automatically pause and retry.