Error Codes¶

This page provides a comprehensive reference for error codes used in the UIM Protocol. These error codes are returned by web services when an error occurs during intent execution or other operations.

Error Code Format¶

UIM Protocol error codes follow a standardized format:

UIM-[CATEGORY]-[CODE]

Where: - UIM is the prefix for all UIM Protocol error codes - CATEGORY is a three-letter code indicating the error category - CODE is a three-digit number uniquely identifying the error within its category

For example, UIM-AUT-001 indicates an authentication error with code 001.

Error Response Format¶

When an error occurs, web services should return a response with the following structure:

{
  "error": {
    "code": "UIM-AUT-001",
    "message": "Invalid authentication token",
    "details": {
      "reason": "The token has expired",
      "expiry": "2025-01-01T00:00:00Z"
    },
    "help_url": "https://example.com/docs/errors/UIM-AUT-001"
  }
}

Where: - code is the error code - message is a human-readable error message - details is an optional object containing additional information about the error - help_url is an optional URL pointing to documentation about the error

Error Categories¶

Authentication Errors (AUT)¶

Authentication errors occur when there are issues with the authentication process.

Authorization Errors (AUZ)¶

Authorization errors occur when there are issues with the authorization process.

Validation Errors (VAL)¶

Validation errors occur when there are issues with the request parameters.

Resource Errors (RES)¶

Resource errors occur when there are issues with the requested resources.

Intent Errors (INT)¶

Intent errors occur when there are issues with intent execution.

Policy Errors (POL)¶

Policy errors occur when there are issues with policies.

Server Errors (SRV)¶

Server errors occur when there are issues with the server.

Protocol Errors (PRO)¶

Protocol errors occur when there are issues with the protocol.

Error Handling Best Practices¶

When handling errors in the UIM Protocol, follow these best practices:

1. Use Appropriate Error Codes: Use the most specific error code that applies to the situation.
2. Provide Clear Error Messages: Error messages should be clear, concise, and helpful.
3. Include Relevant Details: Include relevant details in the details field to help diagnose the issue.
4. Use Appropriate HTTP Status Codes: Use the HTTP status code that best matches the error.
5. Provide Help URLs: Include a help_url field pointing to documentation about the error.
6. Log Errors: Log errors on the server side for debugging and monitoring.
7. Handle Errors Gracefully: Clients should handle errors gracefully and provide appropriate feedback to users.
8. Retry with Backoff: For transient errors, clients should retry with exponential backoff.
9. Validate Inputs: Validate inputs before processing to catch errors early.
10. Secure Error Messages: Ensure error messages don't leak sensitive information.

Error Handling Example¶

Server-Side Error Handling¶

function executeIntent(req, res) {
  try {
    // Validate request
    if (!req.body.intent_uid) {
      return res.status(400).json({
        error: {
          code: "UIM-VAL-001",
          message: "Missing required parameter: intent_uid",
          details: {
            parameter: "intent_uid"
          },
          help_url: "https://example.com/docs/errors/UIM-VAL-001"
        }
      });
    }

    // Check authentication
    if (!req.headers.authorization) {
      return res.status(401).json({
        error: {
          code: "UIM-AUT-003",
          message: "Missing authentication token",
          help_url: "https://example.com/docs/errors/UIM-AUT-003"
        }
      });
    }

    // Execute intent
    const result = executeIntentLogic(req.body.intent_uid, req.body.parameters);

    // Return result
    return res.status(200).json(result);
  } catch (error) {
    // Handle unexpected errors
    console.error("Intent execution error:", error);
    return res.status(500).json({
      error: {
        code: "UIM-INT-002",
        message: "Intent execution failed",
        details: {
          reason: error.message
        },
        help_url: "https://example.com/docs/errors/UIM-INT-002"
      }
    });
  }
}

Client-Side Error Handling¶

async function executeIntent(intentUid, parameters) {
  try {
    const response = await fetch("https://api.example.com/uim/execute", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${pat}`
      },
      body: JSON.stringify({
        intent_uid: intentUid,
        parameters: parameters
      })
    });

    const data = await response.json();

    if (!response.ok) {
      // Handle error
      if (data.error) {
        switch (data.error.code) {
          case "UIM-AUT-001":
          case "UIM-AUT-002":
            // Handle authentication errors
            refreshToken();
            break;
          case "UIM-AUZ-004":
            // Handle rate limiting
            await sleep(1000);
            return executeIntent(intentUid, parameters);
          case "UIM-INT-003":
            // Handle timeout
            return executeIntent(intentUid, parameters);
          default:
            // Handle other errors
            throw new Error(`${data.error.code}: ${data.error.message}`);
        }
      } else {
        throw new Error(`HTTP error: ${response.status}`);
      }
    }

    return data;
  } catch (error) {
    console.error("Error executing intent:", error);
    throw error;
  }
}

References¶

• HTTP Status Codes
• JSON API Errors
• OAuth 2.0 Error Codes
• UIM Protocol API Guidelines