Error Codes

The Protocol uses a minimal set of essential error codes optimized for simplicity and fast implementation.

Essential Error Codes

Total 8 error codes that cover 95% of scenarios:

Error Code	Description	Retry?	HTTP Status
`invalid_signature`	Message signature verification failed	No	401
`capability_not_found`	Requested capability not available	No	404
`invalid_parameters`	Missing or invalid task parameters	No	400
`processing_failed`	Error during task execution	Yes	500
`resource_unavailable`	Service temporarily unavailable	Yes	503
`rate_limited`	Too many requests from this agent	Yes	429
`invalid_message_format`	Message doesn't match expected format	No	400
`agent_not_found`	Target agent doesn't exist	No	404

Error Message Format

{
  "from": "hive:agentid:provider456",
  "to": "hive:agentid:client123",
  "type": "task_error",
  "data": {
    "task_id": "task-123",
    "error": "capability_not_found",
    "message": "text-translation not available",
    "retry": false
  },
  "sig": "ed25519_signature"
}

Implementation Examples

Basic Error Handling

// Simple error response function
function sendError(taskId, requester, errorCode, message, canRetry = false) {
  const errorResponse = {
    from: AGENT_ID,
    to: requester,
    type: "task_error",
    data: {
      task_id: taskId,
      error: errorCode,
      message: message,
      retry: canRetry,
    },
  };

  return {
    ...errorResponse,
    sig: signMessage(errorResponse),
  };
}

// Usage in endpoint
app.post("/tasks", (req, res) => {
  const message = req.body;

  // Validate signature
  if (!verifySignature(message)) {
    return res
      .status(401)
      .json(
        sendError(
          message.data?.task_id,
          message.from,
          "invalid_signature",
          "Signature verification failed"
        )
      );
  }

  // Check capability
  const capability = findCapability(message.data.capability);
  if (!capability) {
    return res
      .status(404)
      .json(
        sendError(
          message.data.task_id,
          message.from,
          "capability_not_found",
          `${message.data.capability} not available`
        )
      );
  }

  // Validate parameters
  if (!validateParameters(capability, message.data)) {
    return res
      .status(400)
      .json(
        sendError(
          message.data.task_id,
          message.from,
          "invalid_parameters",
          "Required parameters missing"
        )
      );
  }

  try {
    // Process task
    const result = processTask(message.data.capability, message.data);
    res.json(createSuccessResponse(message.data.task_id, message.from, result));
  } catch (error) {
    res
      .status(500)
      .json(
        sendError(
          message.data.task_id,
          message.from,
          "processing_failed",
          error.message,
          true
        )
      );
  }
});

Error Handling Best Practices

// Rate limiting implementation
const rateLimiter = new Map();

function checkRateLimit(agentId) {
  const now = Date.now();
  const requests = rateLimiter.get(agentId) || [];

  // Remove requests older than 1 minute
  const recentRequests = requests.filter((time) => now - time < 60000);

  if (recentRequests.length >= 60) {
    // 60 requests per minute
    return false;
  }

  recentRequests.push(now);
  rateLimiter.set(agentId, recentRequests);
  return true;
}

// Resource availability check
function checkResourceAvailability() {
  // Simple health check
  const memoryUsage = process.memoryUsage();
  const cpuUsage = process.cpuUsage();

  if (memoryUsage.heapUsed > 500 * 1024 * 1024) {
    // 500MB limit
    return false;
  }

  return true;
}

Optional: Extended Error Codes

Additional error codes for advanced implementations:

Error Code	Description	When to Use
`timeout`	Task execution timeout	Long-running tasks
`insufficient_resources`	Not enough compute/memory	Resource-intensive tasks
`dependency_failed`	Required service unavailable	Multi-service tasks
`validation_failed`	Result validation failed	Quality assurance
`permission_denied`	Authorization failed	Access control

Client Error Handling

// Simple client-side error handling
async function sendTaskRequest(agentEndpoint, taskRequest) {
  try {
    const response = await fetch(`${agentEndpoint}/tasks`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(taskRequest),
    });

    const result = await response.json();

    if (result.type === "task_error") {
      const { error, message, retry } = result.data;

      switch (error) {
        case "capability_not_found":
          console.log(`❌ Capability not available: ${message}`);
          break;
        case "processing_failed":
          if (retry) {
            console.log(`🔄 Retrying task: ${message}`);
            // Implement retry logic
          } else {
            console.log(`❌ Task failed: ${message}`);
          }
          break;
        case "rate_limited":
          console.log(`⏳ Rate limited, waiting before retry: ${message}`);
          // Implement backoff
          break;
        default:
          console.log(`❌ Unknown error: ${error} - ${message}`);
      }
    }

    return result;
  } catch (error) {
    console.error("Network error:", error);
    throw error;
  }
}

Simplicity Focus: The 8 essential error codes handle 95% of real-world scenarios. Start with these and add more only if you encounter specific errors that don't fit.

Security: Never include sensitive information in error messages. Keep error details generic to prevent information leakage.