Structured Error Codes Specification

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

interface ErrorResponse {
  success: false;
  error: ErrorDetail;
}

interface ErrorDetail {
  /**
   * Machine-readable error code
   * Format: CATEGORY_SPECIFIC_ERROR
   */
  code: string;

  /**
   * Human-readable error message
   */
  message: string;

  /**
   * Optional contextual details
   */
  details?: Record<string, unknown>;
}

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

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

{
  /** Name of the missing parameter */
  param_name: string;
  /** Operation that requires this parameter */
  operation?: string;
}

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

{
  /** Name of the invalid parameter */
  param_name: string;
  /** Expected type (string, integer, etc.) */
  expected_type: string;
  /** Type that was received */
  actual_type: string;
  /** The invalid value (if safe to include) */
  value?: unknown;
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_INVALID_TYPE",
    "message": "Parameter 'per_page' expected 'integer', got 'string'",
    "details": {
      "param_name": "per_page",
      "expected_type": "integer",
      "actual_type": "string",
      "value": "fifty"
    }
  }
}

{
  /** The operation being called */
  operation: string;
  /** List of unknown parameter names */
  unknown_params: string[];
  /** List of valid parameter names for this operation */
  valid_params: string[];
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_UNKNOWN_PARAM",
    "message": "Unknown parameter(s) for operation 'create_user': force_create, admin_override",
    "details": {
      "operation": "create_user",
      "unknown_params": ["force_create", "admin_override"],
      "valid_params": ["user_name", "password", "email"]
    }
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_UNKNOWN_PARAM",
    "message": "Unknown parameter(s) for operation 'create_user': force_create",
    "details": {
      "operation": "create_user",
      "unknown_params": ["force_create"],
      "valid_params": ["user_name", "password", "email"]
    }
  }
}

{
  /** Location where invalid encoding was detected */
  location?: string;
  /** Byte offset of the invalid sequence (if available) */
  byte_offset?: number;
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_INVALID_ENCODING",
    "message": "Invalid character encoding in request",
    "details": {
      "location": "params.description",
      "byte_offset": 42
    }
  }
}

{
  /** Type of limit exceeded */
  limit_type: 'request_size' | 'response_size' | 'string_length' | 'array_elements' | 'nesting_depth';
  /** The configured limit */
  limit_value: number;
  /** The actual size/count */
  actual_value: number;
  /** Unit of measurement */
  unit: 'bytes' | 'elements' | 'levels';
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_PAYLOAD_TOO_LARGE",
    "message": "Payload exceeds request_size limit of 1048576",
    "details": {
      "limit_type": "request_size",
      "limit_value": 1048576,
      "actual_value": 2500000,
      "unit": "bytes"
    }
  }
}

{
  /** The operation name that was requested */
  operation: string;
  /** Valid operation names the client can use instead */
  available?: string[];
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND_OPERATION",
    "message": "Unknown operation: 'get_users'",
    "details": {
      "operation": "get_users"
    }
  }
}

{
  /** Type of resource (e.g., "repository", "user", "issue") */
  resource_type?: string;
  /** Identifier that was not found */
  resource_id?: string;
  /** HTTP status code from the target API */
  http_status?: number;
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND_RESOURCE",
    "message": "Repository 'octocat/nonexistent' not found",
    "details": {
      "resource_type": "repository",
      "resource_id": "octocat/nonexistent",
      "http_status": 404
    }
  }
}

{
  /** Human-readable explanation of why permission was denied */
  reason?: string;
  /** HTTP status code from the target API (401 or 403) */
  http_status?: number;
  /** OAuth scope required for this operation, if known */
  required_scope?: string;
}

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Permission denied: requires 'repo' scope",
    "details": {
      "http_status": 403,
      "required_scope": "repo"
    }
  }
}

{
  /** HTTP status code from the target API */
  http_status?: number;
  /** Error message returned by the target API */
  upstream_error?: string;
}

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error: GitHub API unavailable",
    "details": {
      "http_status": 503,
      "upstream_error": "Service temporarily unavailable"
    }
  }
}

{
  /** The operation that was attempted */
  operation: string;
  /** Trust level required for this operation */
  required_trust: 'untested' | 'generated' | 'validated' | 'community_reviewed' | 'certified';
  /** Adapter's current trust level */
  actual_trust: string;
  /** The danger level of the operation */
  danger_level?: number;
}

{
  "success": false,
  "error": {
    "code": "PERMISSION_TRUST_LEVEL_INSUFFICIENT",
    "message": "Operation 'delete_user' requires trust level 'community_reviewed', adapter has 'validated'",
    "details": {
      "operation": "delete_user",
      "required_trust": "community_reviewed",
      "actual_trust": "validated",
      "danger_level": 2
    }
  }
}

{
  /** The operation that was attempted */
  operation: string;
  /** The danger level of the operation */
  danger_level: 'safe' | 'reversible' | 'destructive' | 'dangerous' | 'forbidden';
  /** Adapter's current trust level */
  adapter_trust: string;
  /** Minimum trust level required */
  minimum_trust_required: string;
  /** Reasons why this operation is dangerous */
  reasons?: string[];
}

{
  "success": false,
  "error": {
    "code": "PERMISSION_DANGER_LEVEL_DENIED",
    "message": "Operation 'bulk_delete' (danger: dangerous) denied for adapter trust level 'validated'",
    "details": {
      "operation": "bulk_delete",
      "danger_level": "dangerous",
      "adapter_trust": "validated",
      "minimum_trust_required": "community_reviewed",
      "reasons": [
        "Affects multiple resources",
        "Cannot be undone"
      ]
    }
  }
}

{
  /** The operation that requires confirmation */
  operation: string;
  /** The danger level of the operation */
  danger_level: string;
  /** Human-readable reasons for the confirmation requirement */
  reasons?: string[];
  /** Custom confirmation message to display */
  confirmation_message?: string;
  /** Token to include in retry request */
  confirmation_token: string;
  /** When the confirmation token expires */
  expires_at: string;
}

{
  "success": false,
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "This operation requires confirmation",
    "details": {
      "operation": "delete_repo",
      "danger_level": "destructive",
      "reasons": [
        "Permanently removes repository and all contents",
        "Cannot be recovered after grace period"
      ],
      "confirmation_message": "Delete repository 'acme/widgets'? This cannot be undone.",
      "confirmation_token": "conf_abc123xyz",
      "expires_at": "2026-01-28T12:05:00Z"
    }
  }
}

{
  /** The rate limit that was exceeded */
  limit: number;
  /** Remaining requests (usually 0) */
  remaining: number;
  /** Time window of the limit */
  window: 'second' | 'minute' | 'hour' | 'day';
  /** When the rate limit resets */
  resets_at: string;
  /** Seconds until retry is allowed */
  retry_after_seconds: number;
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "details": {
      "limit": 5000,
      "remaining": 0,
      "window": "hour",
      "resets_at": "2026-01-28T13:00:00Z",
      "retry_after_seconds": 1847
    }
  }
}

{
  /** The metric that triggered the pause */
  metric: string;
  /** Current usage */
  current: number;
  /** The pause threshold */
  pause_threshold: number;
  /** The hard stop threshold (if configured) */
  hard_stop_threshold?: number;
  /** Token to continue past the pause */
  confirmation_token: string;
  /** When the confirmation token expires */
  expires_at: string;
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_QUOTA_PAUSE",
    "message": "Quota pause threshold reached",
    "details": {
      "metric": "requests_per_hour",
      "current": 4850,
      "pause_threshold": 4800,
      "hard_stop_threshold": 5000,
      "confirmation_token": "quota_continue_abc123",
      "expires_at": "2026-01-28T12:05:00Z"
    }
  }
}

{
  /** The metric that triggered the hard stop */
  metric: string;
  /** Current usage */
  current: number;
  /** The hard stop threshold */
  hard_stop_threshold: number;
  /** When the quota resets */
  resets_at: string;
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_QUOTA_EXHAUSTED",
    "message": "Quota exhausted",
    "details": {
      "metric": "requests_per_hour",
      "current": 5000,
      "hard_stop_threshold": 5000,
      "resets_at": "2026-01-28T13:00:00Z"
    }
  }
}

{
  /** The metric approaching the limit */
  metric: string;
  /** Current usage */
  current: number;
  /** The warning threshold */
  warn_threshold: number;
  /** The pause threshold (next level) */
  pause_threshold?: number;
}

{
  "success": true,
  "data": { "...": "..." },
  "warnings": [
    {
      "code": "RATE_LIMIT_QUOTA_WARNING",
      "message": "Approaching quota limit",
      "details": {
        "metric": "requests_per_hour",
        "current": 4100,
        "warn_threshold": 4000,
        "pause_threshold": 4800
      }
    }
  ]
}

{
  /** The token that was provided */
  token: string;
}

{
  "success": false,
  "error": {
    "code": "TOKEN_INVALID",
    "message": "Invalid confirmation token",
    "details": {
      "token": "conf_nonexistent123"
    }
  }
}

{
  /** The token that expired */
  token: string;
  /** When the token expired */
  expired_at: string;
  /** Current server time */
  current_time: string;
}

{
  "success": false,
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Confirmation token has expired",
    "details": {
      "token": "conf_abc123xyz",
      "expired_at": "2026-01-28T12:05:00Z",
      "current_time": "2026-01-28T12:07:30Z"
    }
  }
}

{
  /** The token that was already used */
  token: string;
  /** When the token was consumed */
  consumed_at?: string;
}

{
  "success": false,
  "error": {
    "code": "TOKEN_ALREADY_USED",
    "message": "Confirmation token has already been used",
    "details": {
      "token": "conf_abc123xyz",
      "consumed_at": "2026-01-28T12:04:15Z"
    }
  }
}

{
  /** The token that was provided */
  token: string;
  /** Operation the token was issued for */
  token_operation: string;
  /** Operation the client is attempting */
  requested_operation: string;
}

{
  "success": false,
  "error": {
    "code": "TOKEN_SCOPE_MISMATCH",
    "message": "Confirmation token scope mismatch",
    "details": {
      "token": "conf_abc123xyz",
      "token_operation": "delete_repo",
      "requested_operation": "force_push"
    }
  }
}

function mapHttpStatusToErrorCode(status: number): string {
  if (status === 400 || status === 422) {
    return 'VALIDATION_INVALID_TYPE';
  }
  if (status === 401 || status === 403) {
    return 'PERMISSION_DENIED';
  }
  if (status === 404) {
    return 'NOT_FOUND_RESOURCE';
  }
  if (status >= 500) {
    return 'INTERNAL_ERROR';
  }
  // Default for other 4xx errors
  return 'VALIDATION_INVALID_TYPE';
}

const ERROR_MESSAGES = {
  en: {
    VALIDATION_MISSING_PARAM: "Missing required parameter: '{param_name}'",
    NOT_FOUND_RESOURCE: 'Resource not found',
  },
  es: {
    VALIDATION_MISSING_PARAM: "Falta el parámetro requerido: '{param_name}'",
    NOT_FOUND_RESOURCE: 'Recurso no encontrado',
  }
};

function localizeError(error: ErrorDetail, locale: string): string {
  const template = ERROR_MESSAGES[locale]?.[error.code];
  if (template && error.details) {
    return interpolate(template, error.details);
  }
  return error.message;
}

# In adapter schema
error_codes:
  GITHUB_ABUSE_DETECTED:
    category: RATE_LIMIT
    message_template: "Abuse detection triggered: {reason}"
    maps_from_http: [403]
    condition: "response.body.message contains 'abuse'"

# In adapter schema
error_mapping:
  404:
    code: NOT_FOUND_REPOSITORY
    message_template: "Repository '{owner}/{repo}' not found"
  403:
    condition: "response.body.message contains 'rate limit'"
    code: RATE_LIMIT_EXCEEDED

{
  "success": false,
  "error": {
    "code": "BATCH_PARTIAL_FAILURE",
    "message": "3 of 5 operations failed",
    "details": {
      "total": 5,
      "succeeded": 2,
      "failed": 3,
      "errors": [
        { "index": 1, "code": "NOT_FOUND_RESOURCE", "message": "..." },
        { "index": 3, "code": "PERMISSION_DENIED", "message": "..." },
        { "index": 4, "code": "VALIDATION_MISSING_PARAM", "message": "..." }
      ]
    }
  }
}